README.md

@@ -1,31 +1,82 @@
-# Immich CLI utilities
+# Immich Tools
 
-`immich-tools` is a small command-line utility interacting with an Immich server. It offers the following features:
+[![Crates.io](https://img.shields.io/crates/v/immich-tools.svg)](https://crates.io/crates/immich-tools)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
- - List named faces that do not have an associated date of birth
+`immich-tools` is a command-line utility for interacting with [Immich](https://immich.app), a self-hosted photo and
- - Synchronise date of births from a vcard file
+video backup solution. This tool provides various utilities to manage your Immich server from the command line.
- - 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.
+## Features
+
+### Albums
+- **List** all albums on your Immich server
+- **Delete** albums (all or empty ones only)
+- **Auto-create** albums from external libraries folder structure
+
+### Assets
+- **List** assets (all or offline only)
+- **Delete** assets (all or offline only)
+
+### External libraries
+- **List** all libraries
+- **Scan** all libraries to detect new assets
+
+### People
+- **List** named faces that do not have an associated date of birth
+- **Synchronize** dates of birth from a vCard file
+
+### Server
+- **Show** server version
+- **Check** which server features are enabled
+
+## Installation
+
+### From Crates.io
+
+```bash
+cargo install immich-tools
+```
+
+### From Source
+
+```bash
+git clone https://git.enoent.fr/kernald/immich-tools.git
+cd immich-tools
+cargo build --release
+```
+
+The binary will be available at `./target/release/immich-tools`.
 
 ## Configuration
 
-Different options need to be passed to this tool, mainly:
+To connect to your Immich server, you need to provide:
 
- - `server_url`: the API endpoint of the Immich instance to work on
+- `server_url`: The API endpoint of your Immich instance (usually ends with `/api`)
- - `api_key`: the API key to use
+- `api_key`: Your Immich API key (can be generated in the Immich web interface)
 
-These can be passed through different mechanisms:
+These can be provided in several ways (in order of precedence):
 
- - Command line arguments, e.g. `immich-tools --server-url https://photos.example.com/api --api-key api-key-goes-here server version`
+1. **Command line arguments**:
- - 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`
+   ```bash
- - 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.
+   immich-tools --server-url https://photos.example.com/api --api-key your-api-key server version
- - 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.
+2. **Environment variables** (prefixed with `IMMICH_TOOLS_`):
+   ```bash
+   IMMICH_TOOLS_SERVER_URL=https://photos.example.com/api IMMICH_TOOLS_API_KEY=your-api-key immich-tools server version
+   ```
 
-### Example configuration file
+3. **Environment variables pointing to files** (suffixed with `_FILE`):
+   ```bash
+   IMMICH_TOOLS_SERVER_URL_FILE=~/immich-url.txt IMMICH_TOOLS_API_KEY_FILE=~/immich-api-key.txt immich-tools server version
+   ```
+
+4. **Configuration file** in the OS-specific location:
+   - Linux: `~/.config/immichtools/config.toml`
+   - macOS: `~/Library/Application Support/fr.enoent.Immich-Tools/config.toml`
+   - Windows: `~\AppData\Roaming\enoent\Immich Tools\config\config.toml`
+
+### Example Configuration File
 
 ```toml
 server_url = "https://photos.example.com/api"
@@ -35,6 +86,86 @@ api_key_file = "/home/example/.config/immichtools/apikey"
 vcard = "/home/example/contacts.vcf"
 ```
 
-## Immich API bindings
+## Usage Examples
 
-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.
+### Albums
+
+List all albums:
+```bash
+immich-tools albums list
+```
+
+Delete empty albums:
+```bash
+immich-tools albums delete --empty
+```
+
+Auto-create albums from folder structure:
+```bash
+immich-tools albums auto-create --album-name-separator "/"
+```
+
+### Assets
+
+List all assets:
+```bash
+immich-tools assets list
+```
+
+List offline assets only:
+```bash
+immich-tools assets list --offline
+```
+
+Delete offline assets:
+```bash
+immich-tools assets delete --offline
+```
+
+### External libraries
+
+List all libraries:
+```bash
+immich-tools libraries list
+```
+
+Scan all libraries for new assets:
+```bash
+immich-tools libraries scan
+```
+
+### People
+
+List people missing date of birth:
+```bash
+immich-tools people missing-date-of-births
+```
+
+Sync dates of birth from vCard file:
+```bash
+immich-tools people sync-date-of-births --vcard /path/to/contacts.vcf
+```
+
+### Server
+
+Show server version:
+```bash
+immich-tools server version
+```
+
+Check enabled server features:
+```bash
+immich-tools server features
+```
+
+## Global Options
+
+- `--dry-run`: Show what would be done without making any changes
+- `--no-confirm`: Skip confirmation prompts
+- `-v, --verbose`: Increase logging verbosity (can be used multiple times)
+
+## Immich API Compatibility
+
+The bindings are generated automatically from the Immich OpenAPI specification. The current version is compatible with
+Immich v1.119.1, with some limitations around file upload operations (Progenitor doesn't yet support
+`multipart/form-data` content types, see [this issue](https://github.com/oxidecomputer/progenitor/issues/518)).