immich

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

--help, -h
    Displays help information for the command or a specific subcommand, detailing available options and usage.

--version, -v
    Prints the current version of the Immich CLI tool.

--host <hostname_or_ip>
    Specifies the hostname or IP address of the Immich server to connect to. This overrides any configured host.

--port <port_number>
    Specifies the port number of the Immich server. This overrides any configured port.

--api-key <key>
    Provides an API key for authentication, bypassing interactive login for script-based operations.

login
    Authenticates the CLI with an Immich server, typically by prompting for username and password to obtain session tokens.

upload
    Uploads photos and videos from local directories to the Immich server. This is one of the most frequently used subcommands and has its own specific options (e.g., --recursive, --album).

config
    Manages the CLI's configuration, such as setting default server connections or clearing cached credentials.

asset
    Interacts with individual assets (photos/videos) on the server, allowing operations like listing, deleting, or viewing details.

user
    Manages user accounts on the Immich server. This subcommand typically requires administrative privileges on the Immich server.

Immich is a high-performance, self-hosted backup solution for photos and videos, designed to be an open-source alternative to Google Photos. The immich-cli command-line interface provides a convenient way to interact with an Immich server from a Linux environment.

It allows users to perform various tasks such as uploading media, managing server configurations, authenticating with the server, and interacting with user accounts and assets. This tool is essential for scripting automated backups, managing large media collections, or integrating Immich into existing workflows. It emphasizes privacy, user control, and robust media management capabilities, making it a popular choice for individuals seeking to self-host their digital memories. The CLI complements the web interface, offering programmatic access to server functionalities without needing direct database or file system access on the server.

The immich-cli tool requires a running Immich server to connect to. Most operations necessitate prior authentication (via login or --api-key).
The available subcommands and their specific options are actively developed and may change between versions; always refer to the specific version's help documentation.
This CLI is for interacting with the server's API, not for managing the server's underlying services (e.g., Docker containers).

The immich-cli tool is typically installed via npm (Node Package Manager), yarn, or by downloading pre-compiled binaries for various operating systems from the official Immich GitHub releases page. It is not usually found in standard Linux distribution repositories.

When using the login subcommand, immich-cli will guide you through entering your server URL and user credentials. Upon successful login, it stores authentication tokens locally, allowing subsequent commands to be executed without re-entering credentials until the tokens expire or are revoked.

Immich is a relatively modern open-source project, with its initial public releases gaining significant traction around 2021-2022. The immich-cli tool was developed as a crucial companion to the main Immich server application, providing command-line capabilities for users and developers to automate tasks, script backups, and interact with the server's API without relying solely on the web interface. Its development closely follows the main Immich project's roadmap, adapting to new features and API changes, and it is a testament to Immich's commitment to providing flexible self-hosting solutions.

docker(1), curl(1)