# Immich CLI utilities

`immich-tools` is a small command-line utility interacting with an Immich server. It offers the following features:

 - List named faces that do not have an associated date of birth
 - Synchronise date of births from a vcard file
 - List and delete assets, including filtering offline assets only
 - Show details about the server

Some other features are planned, mainly around using external libraries. Feature ideas and contributions welcome.

## Configuration

Different options need to be passed to this tool, mainly:

 - `server_url`: the API endpoint of the Immich instance to work on
 - `api_key`: the API key to use

These can be passed through different mechanisms:

 - Command line arguments, e.g. `immich-tools --server-url https://photos.example.com/api --api-key api-key-goes-here server version`
 - Environment variables prefixed with `IMMICH_TOOLS_`, e.g. `IMMICH_TOOLS_SERVER_URL=https://photos.example.com/api IMMICH_TOOLS_API_KEY=api-key-goes-here immich-tools server version`
 - Environment variables pointing to files, suffixed with `_FILE`, e.g. `IMMICHTOOLS_SERVER_URL_FILE=~/immich-url.txt IMMICH_TOOLS_API_KEY_FILE=~/immich-api-key.txt immich-tools server version`. This is mostly useful for secrets.
 - Through a configuration file, in a well-known, OS-dependent location (on Linux, `~/.config/immichtools/config.toml`, on macOS, `~/Library/Application Support/fr.enoent.Immich-Tools/config.toml`, and on Windows `~\AppData\Roaming\enoent\Immich Tools\config\config.toml`). Note that keys in this file can also be suffixed with `_file` and point to a file containing the value, instead of the value directly.

Command line arguments take precedence over environment variables, which in turn take precedence over the configuration file.

### Example configuration file

```toml
server_url = "https://photos.example.com/api"
api_key_file = "/home/example/.config/immichtools/apikey"

[people.sync_date_of_births]
vcard = "/home/example/contacts.vcf"
```

## Immich API bindings

The bindings are generated automatically from `src/immich-openapi-specs.json`. The file currently in the repo has been generated with Immich v1.119.1, with a few methods removed around file upload (Progenitor doesn't yet support `multipart/form-data` content types, see [here](https://github.com/oxidecomputer/progenitor/issues/518)). All other methods should be available.