immich-go

Upload a Google Photos takeout file to Immich server

$ immich-go -server=[server_url] -key=[server_key] upload [path/to/takeout_file.zip]

$ immich-go -server=[server_url] -key=[server_key] upload -create-albums -google-photos -date=[2019-06] [path/to/takeout_file.zip]

$ immich-go -use-configuration=[~/.immich-go/immich-go.json] upload [path/to/takeout_file.zip]

$ immich-go -server=[server_url] -key=[server_key] duplicate -yes

$ immich-go -server=[server_url] -key=[server_key] tool album delete [\d{4}-\d{2}-\d{2]}

immich-go command [options] [arguments]

Common Commands:
immich-go login
immich-go upload [path ...]
immich-go download asset-ids
immich-go album [subcommand]
immich-go config [subcommand]
immich-go status

--server URL
    Specifies the URL of the Immich server (e.g., http://localhost:2283). Overrides the configuration file setting.

--key API_KEY
    Provides the API key for authentication. This is an alternative to using immich-go login.

--config PATH
    Specifies an alternative path to the configuration file. Defaults to ~/.immich-go.yml.

--log-level LEVEL
    Sets the logging verbosity (e.g., debug, info, warn, error). Default is info.

--concurrency NUMBER
    Defines the number of concurrent uploads/downloads. Improves performance for large batches.

--dry-run
    Simulates the command without making any actual changes to the Immich server or local files. Useful for testing.

--recursive, -r
    (upload command) Recursively scans subdirectories for media files to upload.

--checksum
    (upload command) Forces checksumming of files for duplicate detection, even if not enabled by default.

--no-dupes
    (upload command) Skips files that are already present on the Immich server based on checksum or filename.

--create-albums
    (upload command) Creates albums on the Immich server based on the names of local directories being uploaded.

--exclude-patterns PATTERNS
    (upload command) Specifies a comma-separated list of glob patterns to exclude files or directories from being processed.

immich-go is a powerful command-line interface (CLI) client designed to interact with an Immich server. Immich is an open-source, self-hosted photo and video backup solution, similar to Google Photos. This Go-based tool provides robust functionalities for managing media assets, primarily focusing on uploading and synchronizing large collections of photos and videos from local file systems to an Immich instance.

Key features include intelligent duplicate detection using checksums, recursive directory scanning, and the ability to organize uploads into albums based on directory structure or specified names. It supports various configuration options, including server URL, API key management, and concurrency settings for efficient transfers. Beyond uploads, immich-go can also facilitate downloading assets, managing existing albums, and performing administrative tasks, making it an essential utility for users who prefer automation, bulk operations, or command-line workflows for their Immich media library.

Requires a running Immich server instance to connect to.
Authentication (via API key or login) is mandatory for most operations.
Performance is highly dependent on network speed and server resources.
Compatibility: Ensure immich-go version is compatible with your Immich server's API version, especially after major Immich updates.
Not all Immich server features are exposed via the CLI; some advanced management may still require the web UI.

immich-go typically stores its configuration, including server URL and API key, in a YAML file, commonly located at ~/.immich-go.yml. This file can be manually edited or managed using the immich-go config subcommands. Settings can also be overridden by command-line options for specific operations.

To authenticate with the Immich server, use the immich-go login command. This will prompt for the server URL and API key, saving them to the configuration file. Alternatively, the --key option can be used directly for single commands or scripting, especially useful in CI/CD environments or temporary sessions.

A frequent use case for immich-go is an initial bulk upload of an existing photo library: immich-go upload --recursive --create-albums /path/to/my/photos. For periodic synchronization, users might run a similar command, relying on duplicate detection to skip already uploaded files. It's also invaluable for downloading specific assets or managing albums programmatically.

immich-go emerged as a community-driven initiative to provide a robust and efficient command-line client for the Immich self-hosted media solution. While Immich offers its own mobile applications and a web interface, there was a growing need for a dedicated CLI tool capable of handling large-scale uploads, automated backups, and scripting complex interactions. Developed independently in Go, immich-go benefits from Go's strong concurrency features and cross-platform capabilities, making it a reliable choice for users looking to manage their Immich libraries from the terminal. Its development closely tracks the Immich server's API, adapting to new features and changes to maintain compatibility and extend functionality.

curl(1), rsync(1), find(1), grep(1)