Immich CLI utilities

immich-tools is a small command-line utility interacting with an Immich server. It offers the following features:

• List named faces that do not have an associated date of birth
• Synchronise date of births from a vcard file
• List and delete assets, including filtering offline assets only
• Show details about the server

Some other features are planned, mainly around using external libraries. Feature ideas and contributions welcome.

Configuration

Different options need to be passed to this tool, mainly:

• server_url: the API endpoint of the Immich instance to work on
• api_key: the API key to use

These can be passed through different mechanisms:

• Command line arguments, e.g. immich-tools --server-url https://photos.example.com/api --api-key api-key-goes-here server version
• Environment variables prefixed with IMMICH_TOOLS_, e.g. IMMICH_TOOLS_SERVER_URL=https://photos.example.com/api IMMICH_TOOLS_API_KEY=api-key-goes-here immich-tools server version
• Environment variables pointing to files, suffixed with _FILE, e.g. IMMICHTOOLS_SERVER_URL_FILE=~/immich-url.txt IMMICH_TOOLS_API_KEY_FILE=~/immich-api-key.txt immich-tools server version. This is mostly useful for secrets.
• Through a configuration file, in a well-known, OS-dependent location (on Linux, ~/.config/immichtools/config.toml, on macOS, ~/Library/Application Support/fr.enoent.Immich-Tools/config.toml, and on Windows ~\AppData\Roaming\enoent\Immich Tools\config\config.toml). Note that keys in this file can also be suffixed with _file and point to a file containing the value, instead of the value directly.

Command line arguments take precedence over environment variables, which in turn take precedence over the configuration file.

Example configuration file

server_url = "https://photos.example.com/api"
api_key_file = "/home/example/.config/immichtools/apikey"

[people.sync_date_of_births]
vcard = "/home/example/contacts.vcf"

Immich API bindings

The bindings are generated automatically from src/immich-openapi-specs.json. The file currently in the repo has been generated with Immich v1.119.1, with a few methods removed around file upload (Progenitor doesn't yet support multipart/form-data content types, see here). All other methods should be available.