Skip to content

Getting Started

Installation

You need Python 3.10–3.14 installed to be able to use this CLI.

uv add immichpy --extra cli

pip install immichpy[cli]

Shell completion

Install shell completion for easier command-line usage. The command auto-detects the shell and installs the completion for it.

$ immichpy --install-completion

fish completion installed in ~/.config/fish/completions/immichpy.fish
Completion will take effect once you restart the terminal
You will get auto-completion for the commands and options when hitting the Tab key.

Performance

Due to the size of the CLI and Python's runtime overhead, the auto-completion is not as fast as I hoped it could be (see typer#231).

Setup

  1. Have your Immich server running or use the demo server.
  2. Get an API key from your Immich account settings.

Create a profile

Using profiles allows you to use the CLI with different servers and reuse configurations easily.

$ immichpy setup

# Enter your server URL: $ https://demo.immich.app/api
# Enter your API key: $ ********

Profile 'default' created successfully!

Validation

The server is validated when you run immichpy setup. The CLI will fail if the server is not reachable.

See immichpy setup for the full command reference.

First commands

That's it! You can now run interact with the Immich server using the CLI.

$ immichpy server get-about-info

{
  "build": "20375083601",
  "version": "v2.4.1",
}

You can also get the information in a different format, e.g. as a table:

$ immichpy --format table server get-about-info

┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Key      ┃ Value          ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ build    │ 20375083601    │
│ version  │ v2.4.1         │
└──────────┴────────────────┘

To see all available commands, run immichpy --help or see the reference.