CLI/Command line tool

In general it 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 static gallery

You can list the help of available commands and options via gallery -h.

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     Build database from file indices, extracted meta data
                          and preview files from the storage
  gallery.js server       Start web server
  gallery.js storage      Storage utils
  gallery.js export       Create a static export
  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"]
                                                               [default: "info"]
  -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]

(c) 2022 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"]
                                                               [default: "info"]
  -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]

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"]
                                                               [default: "info"]
  -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]

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"]
                                                               [default: "info"]
  -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]

Note

The server command starts only the local web server. Photos and videos have to be imported manually to update the media database

run import command

The import command

  • creates or updates the file indices

  • extracts meta data and calculates previews

  • build the media database

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"]
                                                               [default: "info"]
  -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]
  -h, --help            Show help                                      [boolean]

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 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 command

The export command

  • Exports a static gallery

  • Requires only static webserver like nginx or Apache

  • Supports subset exports via query

gallery.js export

Create a static export

Options:
      --version         Show version number                            [boolean]
  -l, --log-level       console log level
         [string] [choices: "trace", "debug", "info", "warn", "error", "silent"]
                                                               [default: "info"]
  -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]

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"]
                                                               [default: "info"]
  -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]
  -h, --help               Show help                                   [boolean]

storage command

The storage command

  • Purges unused and orphan files

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"]
                                                               [default: "info"]
  -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
  -h, --help            Show help                                      [boolean]

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"]
                                                               [default: "info"]
  -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]
  -h, --help               Show help                                   [boolean]
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