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-options] [arguments]

Common commands include:
immich-cli upload [options] [files/directories...]
immich-cli config [options] [key] [value]
immich-cli login
immich-cli logout
immich-cli check
immich-cli version

Global Options
    Options applicable to all immich-cli commands.

--help, -h
    Displays help information for the command or a subcommand.

--version, -v
    Shows the installed immich-cli version.

--debug
    Enables verbose debug output for troubleshooting purposes.

--host
    Specifies the Immich server URL. Can be set persistently via the 'config' subcommand.

--api-key
    Provides the API key for server authentication. Can be set persistently via 'config'.

upload Command Options
    Options specific to the 'upload' subcommand, used for uploading files and directories.

[files/directories...]
    One or more paths to files or directories to be uploaded.

--recursive, -r
    Recursively uploads all supported media files found within specified directories.

--album
    Assigns uploaded files to a specific album on the Immich server. Creates the album if it doesn't exist.

--key
    Provides a unique identifier for the upload session, enabling resumable uploads.

--skip-hash-check
    Skips checking if a file's hash already exists on the server, potentially speeding up uploads of already existing files.

--delete-local
    Deletes local files from the filesystem after successful upload to the server. Use with extreme caution.

--dry-run
    Simulates the upload process without actually performing any file transfers or modifications.

--force
    Forces the upload even if conflicts or existing files are detected on the server.

--no-confirm
    Bypasses all interactive confirmation prompts during the upload process.

--recursive-skip-hidden
    Excludes hidden files and directories (those starting with '.') during recursive uploads.

--exclude
    Excludes files matching the given glob pattern from being uploaded.

--exclude-if-present
    Excludes directories that contain a specific file (e.g., '.nomedia') from being uploaded.

config Command Actions
    Actions for managing immich-cli configuration settings persistently.

set
    Sets a configuration key to a specified value (e.g., 'host', 'api-key').

get
    Retrieves and displays the value of a specific configuration key.

show
    Displays all currently stored immich-cli configuration settings.

clear
    Clears all stored immich-cli configuration settings, requiring re-login or manual host/API key specification.

immich-cli is a command-line interface tool designed to interact with the Immich self-hosted photo and video backup solution. It provides functionalities to manage media files and server configurations directly from the terminal, making it ideal for automation, scripting, and batch operations. Users can upload individual files or entire directories, organize uploads into specific albums, and manage server connection details (like host URL and API keys). The tool supports features like recursive uploads, dry-runs to preview actions, and options to handle existing files or skip hidden directories. It's a crucial component for power users and administrators looking to integrate Immich into their existing workflows or perform large-scale media management tasks efficiently without relying on the web interface.

immich-cli requires an active and accessible Immich server instance for all operations.
Proper authentication (via API Key) is crucial for performing any actions on the server, especially uploads.
The --delete-local option is destructive; always test with --dry-run first and ensure proper backups before use.
Performance for large-scale uploads is highly dependent on network bandwidth and the Immich server's processing capabilities.

immich-cli allows persistent configuration using the config subcommand, which stores settings like the server host and API key. This avoids repeatedly specifying these details for every command. For example, configure it once with: immich-cli config set host https://your.immich.server and immich-cli config set api-key your-api-key-here.

The CLI is particularly powerful for setting up automated backup routines. Users can schedule cron jobs or scripts to periodically upload new photos or videos from specific directories to their Immich server, leveraging options like --recursive and --skip-hash-check for efficient incremental backups. This is ideal for continuous synchronization of local media folders.

The --debug flag is invaluable for troubleshooting connection issues, authentication problems, or unexpected upload behaviors. It provides verbose output detailing the CLI's operations, API interactions, and any encountered errors, significantly aiding in problem diagnosis.

Immich, as a self-hosted media solution, gained significant traction in the self-hosting community, leading to the development of robust tools for interaction. immich-cli emerged as an essential companion tool, designed to provide power users and administrators with a programmatic way to manage their media libraries. Its development closely tracks the evolution of the main Immich server, ensuring compatibility and leveraging new API features. It addresses the need for batch processing, automated backups, and scripted media organization, moving beyond the capabilities offered by the web interface or mobile apps alone.

rclone(1), fdupes(1), rsync(1)