CLI/Command line tool
In general HOmeGallery is a command line tool to init the configuration, start the web server and import the media sources. It has further commands to execute sub task to
Create and update file index of your media directories
Extract meta data and calculate previews
Build the gallery database
Extract meta data to xmp sidecar files
Extract static gallery
Fetch a remote HomeGallery to the local gallery
Stream media to Google Chromecast
You can list the help of available commands and options via gallery -h.
See the Install section how to start the CLI in your environment.
By default it starts in the interactive mode. The run command should be used
for scripting, eg. for cron jobs. Other commands can be used in advance use
cases.
To run the CLI your gallery settings are configured in gallery.config.yml.
It should be initialized via the run init command.
See Configuration section for configuration details.
General help
Usage: gallery.js [global options] <command> [options]
Commands:
gallery.js index File index
gallery.js extract Extract meta data and calculate preview files
gallery.js database Database commands
gallery.js server Start web server
gallery.js storage Storage utils
gallery.js export Export commands
gallery.js fetch Fetch and merge from remote
gallery.js cast Cast media slideshow to Google Chromecast
gallery.js interactive Interactive menu [default]
gallery.js run Run common tasks
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-c, --config Configuration file
-h, --help Show help [boolean]
--level [default: debug]
(c) 2023 HomeGallery - https://home-gallery.org
run command
The run command runs common task
gallery.js run
Run common tasks
Commands:
gallery.js run init Initialize the gallery configuration
gallery.js run server Start the webserver
gallery.js run import Import and update new files from sources
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-c, --config Configuration file
-h, --help Show help [boolean]
--level [default: debug]
run init command
gallery.js run init
Initialize the gallery configuration
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-c, --config Configuration file
-s, --source Initial source directory or directories
[array] [required]
-f, --force Force, overwrite existing configuration [boolean]
-h, --help Show help [boolean]
--level [default: debug]
Use the --source parameter to initialize your media directories. You can edit
the sources later in the gallery.config.yml configuration.
See Configuration section for all available configuration options.
run server command
gallery.js run server
Start the webserver
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-c, --config Configuration file
-h, --help Show help [boolean]
--level [default: debug]
Note
The server command starts the local web server.
Source directories are imported and watched for changes
by default
run import command
The import command
creates or updates the file indices
extracts meta data and calculates previews
build the media database
watch for file changes
gallery.js run import
Import and update new files from sources
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-c, --config Configuration file
-i, --initial Run initial incremental import [boolean]
-u, --update Check and import new files [boolean]
-s, --small-files Import only small files up to 20MB to exclude big
files such as videos to speed up the initial import
[boolean]
-w, --watch Watch files for changes and run import on changes
[boolean]
--watch-delay Delay import after file change detection in
seconds. A new file change refreshes the previous
delay [number] [default: 10]
--watch-max-delay Maximum delay after file change detection in
seconds. Set it to 0 for immediate import on file
change [number] [default: 600]
--watch-poll-interval Use poll interval in seconds. If set 0 watch mode
uses fs events if available. [number] [default: 0]
--import-on-start Run import on watch start [boolean] [default: true]
-h, --help Show help [boolean]
--level [default: debug]
The import command supports 3 modes
Initial/incremental import
Update import
Full import
At the beginning you should use the initial import. It batches the import in several chunks to build the database step by step. At the beginning the chunks are small and database updates are done frequently. If you have a many files in the database the chunk sizes grow and database updates happens less frequently.
When all media are imported and processed you should run update import to import only new unknown files. Eg. if you copied new camera files from your memory cart to your hard drive.
The full import processes all files and checks for missing meta data or preview files. This mode should be run after your finished the initial import - just to be safe. This mode is slow since all media files, meta data and previews needs to be checked.
Note
The watch mode should use the polling mechanism for larger, slow or remote media repositories. An polling interval of at least 5 min is recommended.
Note
The import command can run in parallel to the server.
If the database is updated, the server and webapp will reload it
by default.
Note
If the import command is aborted (eg. by the user), you should run
a full import to ensure that all meta data and all previews are
available.
export static command
The export meta command
Exports a static gallery
Requires only static webserver like nginx or Apache
Supports subset exports via query
gallery.js export static
Create a static website export
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-d, --database Database filename [required]
-e, --events Events filename
-s, --storage Storage directory [required]
-o, --output Output directory of export
-f, --file Archive filename of export. Must end with .zip or
.tar.gz [string]
-k, --keep Keep outputdirectory on archives [boolean]
-q, --query Search query for matching entries [string]
-b, --base-path Base path of static page. e.g. "/gallery"
[string] [default: "/"]
--edit Enable edit menu [boolean] [default: false]
-h, --help Show help [boolean]
--level [default: debug]
export meta command
The export meta command
Exports meta data to XMP sidecar files
All media with manual tags from HomeGallery are written to XMP sidecar files. By default
it will create <name>.<ext>.xmp file. E.g. for the image IMG_1234.JPG
the sidecar IMG_1234.JPG.xmp is created. If IMG_1234.xmp exists it will
use this file.
The tags are written through Exiftool to following namespaces:
Dublin Core (see Exiftool dc Tags)
Digikam (see Exiftool digiKam Tags)
Lightroom (see Exiftool lr Tags)
gallery.js export meta
Export meta data to xmp sidecar files
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-d, --database Database filename [required]
-e, --events Events filename
-i, --index Index file [array] [required]
-A, --changes-after Only write meta data changes after given date (in ISO
8601) [string]
-n, --dry-run Do not perform any writes [boolean] [default: false]
-h, --help Show help [boolean]
--level [default: debug]
fetch command
The fetch command
Fetches a remote gallery
Merges remote database and events from local
Downloads remote previews to local storage
Supports subset imports via query
gallery.js fetch
Fetch and merge from remote
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-u, --server-url, --url Gallery server url [required]
-k, --insecure Do not verify HTTPS certificates [boolean]
-q, --query Search query [string]
-d, --database Database filename [required]
-e, --events Events filename [required]
-s, --storage Storage directory [required]
-D, --delete Delete local files which are missing remote for all
remote index [boolean] [default: false]
-w, --watch Watch server for database change and fetch remote on
changes [boolean] [default: false]
--force-download Force to download and overwrite preview files. Use
this option if the remote preview content changed
(e.g. through a fix) [boolean] [default: false]
--download-all Download preview files from all remote entries. Use
this option if preview files are missing from remote
[boolean] [default: false]
-h, --help Show help [boolean]
--level [default: debug]
database command
The database command
Remove database entries by query
gallery.js database remove
Remove entries by given query
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-d, --database Database filename
-e, --events Events filename
-q, --query Query to remove from the database [string] [required]
-k, --keep, --inverse Keep matching entries instead of removing it [boolean]
-n, --dry-run Do not perform any writes
-c, --config Configuration file
-h, --help Show help [boolean]
--level [default: debug]
Examples:
gallery.js database remove -q Remove all entries with tag
tag:trashed "trashed"
gallery.js database remove -k -q Keep all entries with tag "good"
tag:good
storage command
The storage command
Purges unused and orphan files from the storage directory
gallery.js storage purge
Purge orphean storage files
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-s, --storage Storage directory [required]
-d, --database Database file [required]
-i, --index Optional index file [array]
-n, --dry-run Do not perform any writes [boolean]
-h, --help Show help [boolean]
--level [default: debug]
cast command
The cast command
Cast a slideshow to a Chromecast-enabled TV
Supports subsets via query
gallery.js cast
Cast media slideshow to Google Chromecast
Options:
--version Show version number [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
--log-json-format Log output format in json [boolean]
-L, --log-file Log file
--log-file-level Log file level
[string] [choices: "trace", "debug", "info", "warn", "error"] [default:
"debug"]
-u, --server-url, --url Gallery server url [required]
-q, --query Search query [string]
--proxy Use HTTP proxy. Chromecast does not support internal
DNS and self-signed certificates. The proxy bypasses
this limit. Use --no-proxy to disable it for public
galleries [boolean] [default: true]
--proxy-ip Use given IP for proxy. Auto detect if not given
-p, --port Proxy port [number] [default: 38891]
-k, --insecure Do not verify HTTPS certificates. Disable it by
--no-insecure if you know what you do [boolean]
-s, --random, --shuffle Randomize playback. Use --no-random for linear order
[boolean]
-r, --reverse Reverse order. Default order is by date oldest first
[boolean]
--delay Delay between the images in seconds
[number] [default: 5]
--max-preview-size Maximum size of preview images
[number] [default: 1920]
-h, --help Show help [boolean]
--level [default: debug]
- Example:
./gallery cast -u https://demo.home-gallery.org
Note
Cast command does not work inside a docker container by default. The cast command needs to run in the same network as Google’s Chromecast device. Please ensure that your docker container runs in the same network