CLI Usage¶

The main entrypoint is cmd/main.go, which provides a Cobra-based CLI with multiple commands.

Command Structure¶

immich-stack [command] [flags]

Available Commands¶

(default) - Main stacking functionality (when no command is specified)
duplicates - Find and list duplicate assets
fix-trash - Fix incomplete trash operations for stacks
help - Display help information

Basic Usage¶

# Run the main stacking command
./immich-stack --api-key your_key --api-url http://immich:2283

# Run duplicates command
./immich-stack duplicates --api-key your_key

# Run fix-trash command
./immich-stack fix-trash --api-key your_key

# Get help
./immich-stack --help

# Get help for a specific command
./immich-stack duplicates --help

Command Line Flags¶

Global Flags (All Commands)¶

Flag	Env Var	Description
`--api-key`	`API_KEY`	Immich API key (comma-separated for multiple)
`--api-url`	`API_URL`	Immich API base URL
`--log-level`	`LOG_LEVEL`	Log verbosity: debug, info, warn, error
`--log-format`	`LOG_FORMAT`	Log format: text or json

Stack Command Flags¶

Flag	Env Var	Description
`--reset-stacks`	`RESET_STACKS`	Delete all existing stacks before processing (only in `RUN_MODE=once`)
`--confirm-reset-stack`	`CONFIRM_RESET_STACK`	Required for RESET_STACKS. Must be set to: 'I acknowledge all my current stacks will be deleted and new one will be created'
`--replace-stacks`	`REPLACE_STACKS`	Replace stacks for new groups
`--dry-run`	`DRY_RUN`	Simulate actions without making changes
`--criteria`	`CRITERIA`	Custom grouping criteria
`--parent-filename-promote`	`PARENT_FILENAME_PROMOTE`	Substrings to promote as parent filenames
`--parent-ext-promote`	`PARENT_EXT_PROMOTE`	Extensions to promote as parent files
`--with-archived`	`WITH_ARCHIVED`	Include archived assets in processing
`--with-deleted`	`WITH_DELETED`	Include deleted assets in processing
`--run-mode`	`RUN_MODE`	Run mode: "once" (default) or "cron"
`--cron-interval`	`CRON_INTERVAL`	Interval in seconds for cron mode
`--log-level`	`LOG_LEVEL`	Log level: debug, info, warn, error
`--remove-single-asset-stacks`	`REMOVE_SINGLE_ASSET_STACKS`	Remove stacks containing only one asset
`--filter-album-ids`	`FILTER_ALBUM_IDS`	Filter by album IDs or names (comma-separated, OR logic)
`--filter-taken-after`	`FILTER_TAKEN_AFTER`	Only process assets taken after this date (ISO 8601)
`--filter-taken-before`	`FILTER_TAKEN_BEFORE`	Only process assets taken before this date (ISO 8601)

Command-Specific Notes¶

duplicates: Uses global flags only, particularly --with-archived and --with-deleted to control which assets are checked
fix-trash: Uses global flags plus the stacking criteria flags (--criteria, --parent-filename-promote, etc.) to determine which assets to move to trash

Examples¶

Main Stacking Command¶

immich-stack --api-key your_key --api-url http://immich-server:2283/api

Find Duplicates¶

immich-stack duplicates --api-key your_key --api-url http://immich-server:2283/api

Fix Trash Issues¶

immich-stack fix-trash --api-key your_key --dry-run

Dry Run¶

immich-stack --dry-run --api-key your_key

Custom Parent Selection¶

# Promote edited and raw files
immich-stack \
  --parent-filename-promote edit,raw \
  --parent-ext-promote .jpg,.dng \
  --api-key your_key

# Promote unedited files using empty string
immich-stack \
  --parent-filename-promote ,_edited,_crop \
  --api-key your_key

Include Archived/Deleted¶

immich-stack \
  --with-archived \
  --with-deleted \
  --api-key your_key

Custom Criteria¶

immich-stack \
  --criteria '[{"key":"originalFileName","split":{"delimiters":["~","."],"index":0}},{"key":"localDateTime","delta":{"milliseconds":1000}}]' \
  --api-key your_key

Reset Stacks¶

immich-stack \
  --reset-stacks \
  --confirm-reset-stack "I acknowledge all my current stacks will be deleted and new one will be created" \
  --api-key your_key

Note: --reset-stacks only works when --run-mode is once (or RUN_MODE=once).

Remove Single-Asset Stacks¶

immich-stack \
  --remove-single-asset-stacks \
  --api-key your_key

Asset Filtering¶

# Filter by album ID
immich-stack \
  --filter-album-ids 550e8400-e29b-41d4-a716-446655440000 \
  --api-key your_key

# Filter by album name
immich-stack \
  --filter-album-ids "Vacation Photos" \
  --api-key your_key

# Filter by multiple albums (OR logic)
immich-stack \
  --filter-album-ids "album-1,Vacation Photos,Family" \
  --api-key your_key

# Filter by date range
immich-stack \
  --filter-taken-after 2024-01-01T00:00:00Z \
  --filter-taken-before 2024-12-31T23:59:59Z \
  --api-key your_key

# Combined: album and date filtering
immich-stack \
  --filter-album-ids "My Photos" \
  --filter-taken-after 2024-06-01T00:00:00Z \
  --api-key your_key

Flag Precedence¶

Command line flags take precedence over environment variables
If both are set, the command line flag value is used

Error Handling¶

The CLI provides clear error messages for:

Missing required flags
Invalid flag values
API connection issues
Stack operation failures

Exit Codes¶

Code	Description
0	Success
1	General error
2	Configuration error
3	API error
4	Stack operation error