immich-tools/README.md

# Immich Tools

[![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)

`immich-tools` is a command-line utility for interacting with [Immich](https://immich.app), a self-hosted photo and
video backup solution. This tool provides various utilities to manage your Immich server from the command line.

## Features

### Albums
- **List** all albums on your Immich server
- **Delete** albums (all or empty ones only)
- **Auto-create** albums from external libraries folder structure
- **List assets of an album** by album name

### 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

To connect to your Immich server, you need to provide:

- `server_url`: The API endpoint of your Immich instance (usually ends with `/api`)
- `api_key`: Your Immich API key (can be generated in the Immich web interface)

These can be provided in several ways (in order of precedence):

1. **Command line arguments**:
   ```bash
   immich-tools --server-url https://photos.example.com/api --api-key your-api-key server version
   ```

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
   ```

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"
api_key_file = "/home/example/.config/immichtools/apikey"

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

## Usage Examples

### 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 "/"
```

List assets belonging to a specific album (by album name):
```bash
immich-tools albums list-assets --album "My Album"
```

### 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)).