immich-tools/README.md

Immich Tools

immich-tools is a command-line utility for interacting with Immich, a self-hosted photo and video backup solution. This tool provides various utilities to manage your Immich server from the command line.

Features

Albums

• List all albums on your Immich server
• Delete albums (all or empty ones only)
• Auto-create albums from external libraries folder structure

Assets

• List assets (all or offline only)
• Delete assets (all or offline only)

External libraries

• List all libraries
• Scan all libraries to detect new assets

People

• List named faces that do not have an associated date of birth
• Synchronize dates of birth from a vCard file

Server

• Show server version
• Check which server features are enabled

Installation

From Crates.io

cargo install immich-tools

From Source

git clone https://git.enoent.fr/kernald/immich-tools.git
cd immich-tools
cargo build --release

The binary will be available at ./target/release/immich-tools.

Configuration

To connect to your Immich server, you need to provide:

• server_url: The API endpoint of your Immich instance (usually ends with /api)
• api_key: Your Immich API key (can be generated in the Immich web interface)

These can be provided in several ways (in order of precedence):

1. Command line arguments:

   immich-tools --server-url https://photos.example.com/api --api-key your-api-key server version
   

2. Environment variables (prefixed with IMMICH_TOOLS_):

   IMMICH_TOOLS_SERVER_URL=https://photos.example.com/api IMMICH_TOOLS_API_KEY=your-api-key immich-tools server version
   

3. Environment variables pointing to files (suffixed with _FILE):

   IMMICH_TOOLS_SERVER_URL_FILE=~/immich-url.txt IMMICH_TOOLS_API_KEY_FILE=~/immich-api-key.txt immich-tools server version
   

4. Configuration file in the OS-specific location:

   • Linux: ~/.config/immichtools/config.toml
   • macOS: ~/Library/Application Support/fr.enoent.Immich-Tools/config.toml
   • Windows: ~\AppData\Roaming\enoent\Immich Tools\config\config.toml

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"

Usage Examples

Albums

List all albums:

immich-tools albums list

Delete empty albums:

immich-tools albums delete --empty

Auto-create albums from folder structure:

immich-tools albums auto-create --album-name-separator "/"

Assets

List all assets:

immich-tools assets list

List offline assets only:

immich-tools assets list --offline

Delete offline assets:

immich-tools assets delete --offline

External libraries

List all libraries:

immich-tools libraries list

Scan all libraries for new assets:

immich-tools libraries scan

People

List people missing date of birth:

immich-tools people missing-date-of-births

Sync dates of birth from vCard file:

immich-tools people sync-date-of-births --vcard /path/to/contacts.vcf

Server

Show server version:

immich-tools server version

Check enabled server features:

immich-tools server features

Global Options

• --dry-run: Show what would be done without making any changes
• --no-confirm: Skip confirmation prompts
• -v, --verbose: Increase logging verbosity (can be used multiple times)

Immich API Compatibility

The bindings are generated automatically from the Immich OpenAPI specification. The current version is compatible with Immich v1.119.1, with some limitations around file upload operations (Progenitor doesn't yet support multipart/form-data content types, see this issue).