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
gallery.js plugin Plugin handling
Options:
--version Show version number [boolean]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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) 2024 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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
-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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
-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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
-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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration di
rectories [boolean] [default: true]
-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 f
iles 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 second
s. 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 u
ses 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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration di
rectories [boolean] [default: true]
-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, --prefix 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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
-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 8
601) [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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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 r
emote 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 th
is 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 t
his option if preview files are missing from remote
[boolean] [default: false]
-c, --config Configuration file
--auto-config Search for configuration on common configuration dire
ctories [boolean] [default: true]
-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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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, -c, --config Configuration file
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
-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
-h, --help Show help [boolean]
--level [default: debug]
Examples:
gallery.js database remove -q tag:trashe Remove all entries with tag "trashed
d "
gallery.js database remove -k -q tag:goo Keep all entries with tag "good"
d
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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
-s, --storage Storage directory
-d, --database Database file
-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]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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 g
alleries [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
plugin command (experimental)
The plugin command
Creates or list plugins
gallery.js plugin
Plugin handling
Commands:
gallery.js plugin create Create a new plugin
gallery.js plugin list List plugins [aliases: ls]
gallery.js plugin plugins List plugins [default]
Options:
--version Show version number [boolean]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
-h, --help Show help [boolean]
--level [default: debug]
Note
The plugin feature is quite fresh and handled experimental. Depending on requirements and progress the API might change. You are welcome to test the feature to report your limitations and feature requests
Note
The plugin feature is currently limited to the extractor and database module. Further modules like search and web application should follow. See Plugin for further details
plugin create command
With the create command you can scaffold a plugin. You can choose the source type between vanilla JS or Typescript version. Further you can create extractor steps and or database mappers.
The template shows basic usage and add some data.
gallery.js plugin create
Create a new plugin
Options:
--version Show version number [boolean]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
-n, --name Plugin name [required]
-d, --dir Base directory of plugins. The plugin will be created a
s separate directory of given plugin name below
-t, --sourceType Source language type
[choices: "single", "vanilla", "typescript"] [default: "vanilla"]
-e, --environment Plugin environments
[array] [choices: "server", "browser"] [default: "server"]
-m, --modules Plugin modules. Any set of extractor, database
[array] [choices: "extractor", "database", "query"]
-f, --force Force plugin folder overwrite if exists
[boolean] [default: false]
-h, --help Show help [boolean]
--level [default: debug]
plugin list command
The list command lists active plugins and lists extractors and database mappers. These commands are helpful to validate basic validation if the plugin can be loaded.
gallery.js plugin list
List plugins
Options:
--version Show version number [boolean]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
--long Long version [boolean] [default: false]
--json Print plugins in JSON format [boolean] [default: false]
-h, --help Show help [boolean]
--level [default: debug]
gallery.js plugin list
List plugins
Options:
--version Show version number [boolean]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
--long Long version [boolean] [default: false]
--json Print plugins in JSON format [boolean] [default: false]
-h, --help Show help [boolean]
--level [default: debug]
gallery.js plugin list
List plugins
Options:
--version Show version number [boolean]
--full-version Show full build version [boolean]
-l, --log-level Console log level
[string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
-J, --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
--auto-config Search for configuration on common configuration direct
ories [boolean] [default: true]
--long Long version [boolean] [default: false]
--json Print plugins in JSON format [boolean] [default: false]
-h, --help Show help [boolean]
--level [default: debug]