40 lines
2.3 KiB
Markdown
40 lines
2.3 KiB
Markdown
# 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.
|