Skip to content

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

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

Remove Single-Asset Stacks

immich-stack \
  --remove-single-asset-stacks \
  --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