immich-stack-cli

A small Bun/TypeScript CLI for resolving Immich duplicate groups by stacking every asset in the group.

Immich already supports reviewing duplicate groups and stacking kept assets in the web utility. This CLI adds the missing bulk path:

• stack-all: stack every duplicate group, then remove its duplicate markers.
• review: inspect groups one by one and choose stack, keep all without stacking, or skip.
• list: print duplicate groups without changing anything.

Setup

bun install

Create an Immich API key from your user account settings, then either pass it as flags or set environment variables:

$env:IMMICH_URL = "http://localhost:2283"
$env:IMMICH_API_KEY = "your-api-key"

IMMICH_URL should be the normal Immich server URL. The CLI adds /api automatically unless your URL already ends in /api.

Commands

Preview all duplicate groups:

bun run index.ts list

Dry-run bulk stacking:

bun run index.ts stack-all --dry-run

Bulk stack all duplicate groups:

bun run index.ts stack-all --yes

Review one group at a time:

bun run index.ts review

Review with a local thumbnail preview page opened for each group:

bun run index.ts review --preview

Limit processing while testing:

bun run index.ts stack-all --dry-run --limit 5

You can also pass connection settings directly:

bun run index.ts stack-all --url http://localhost:2283 --key your-api-key --dry-run

Behavior

For each duplicate group, the CLI:

1. Chooses the stack primary from Immich's suggestedKeepAssetIds when available.
2. Falls back to the largest file size, then largest dimensions, then filename.
3. Calls POST /stacks with the primary asset first.
4. Calls PUT /assets with duplicateId: null for every asset in the group.

This mirrors Immich's web utility stack action. The review command's k action still uses POST /duplicates/resolve because that is Immich's "keep all without stacking" path.

If every asset is already in the same stack, the CLI only clears the duplicate marker. If one or more assets are already in another stack, the group is skipped instead of trying to rearrange existing stacks.

stack-all requires --yes for writes. Use --dry-run first.