immich-cli

Authenticate to Immich server

$ immich login [server_url/api] [server_key]

$ immich upload [file1.jpg file2.jpg ...]

$ immich upload --recursive [path/to/directory]

$ immich upload --album-name "[My summer holiday]" --recursive [path/to/directory]

$ immich upload --ignore [**/Raw/** **/*.tif] --recursive [path/to/directory]

$ immich upload --include-hidden --recursive [path/to/directory]

immich-cli [GLOBAL OPTIONS] <COMMAND> [<ARGS>...]

--server, -s <URL>
    Immich server URL (required)

--key, -k <KEY>
    External API key (required)

--machine-learning-endpoint <URL>
    Optional ML endpoint URL

--dry-run
    Simulate without uploading/downloading

--info-log-level <LEVEL>
    Set info log verbosity (off, error, warn, info, debug)

--log-level <LEVEL>
    Set main log verbosity

--timeout <SECONDS>
    Request timeout in seconds (default: 30)

--max-retries <N>
    Max upload retries (default: 3)

--max-parallel-requests <N>
    Max concurrent requests (default: 5)

--info-only
    Scan and info only, no upload

--skip-hash-check
    Skip duplicate hash checks

--skip-duplicates
    Skip uploading known duplicates

--recursive, -r
    Recursively scan directories

--flatten
    Flatten directory structure on upload

--album <NAME>
    Assign to existing album

--person <NAME>
    Assign to person (requires ML)

--yes, -y
    Auto-confirm prompts

-h, --help
    Show help

--version
    Show version

immich-cli is a Rust-based command-line tool for interacting with Immich self-hosted photo and video servers. It enables efficient bulk uploads, backups, downloads, and management of assets directly from the terminal.

Key features include recursive directory scanning, parallel uploads for speed, duplicate detection via hashing, automatic album and person assignment, dry-run mode for testing, and support for machine learning endpoints for facial recognition. Users can backup entire libraries, upload live photos, or download assets with filters.

Designed for automation via cron jobs or scripts, it requires an external API key from the Immich instance. Actively maintained on GitHub, it's ideal for Linux users managing large media collections without a GUI.

Pre-release software; requires valid Immich API key. High parallelism may strain servers. No Windows support in early versions.

cargo install immich-cli or download binary from GitHub releases.

immich-cli backup --server https://immich.example.com --key <key> ~/Photos
immich-cli upload --dry-run --recursive ~/DCIM

backup, upload, upload-live, download, album, asset, person, ml (see immich-cli <command> --help)

Developed by ThomasNLS starting 2023 alongside Immich v1.x. Reaches v0.5+ with subcommands like 'backup', 'upload', 'album'. Frequent updates via Cargo.

rclone(1), rsync(1)