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

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

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