5 ‐ API Reference ‐ Environment Variables

Purpose

Single-page reference for runtime variables and expected values.

Required

Variable	Description	Example
API_KEY	Immich API key, optionally comma-separated	key1,key2
API_URL	Immich API base URL	http://immich:2283/api

Run Mode

Variable	Description	Default
RUN_MODE	once or cron	once
CRON_INTERVAL	Seconds between cron cycles	86400

Stack Management

Variable	Description
DRY_RUN	Simulate operations only
REPLACE_STACKS	Replace stacks that conflict with desired state
RESET_STACKS	Delete all stacks before processing (once mode only)
CONFIRM_RESET_STACK	Required exact confirmation phrase for reset
REMOVE_SINGLE_ASSET_STACKS	Remove single-asset stacks

Parent Selection

Variable	Description	Example
PARENT_FILENAME_PROMOTE	Filename promotion tokens, supports sequence and biggestNumber	cover,edit,sequence
PARENT_EXT_PROMOTE	Extension promotion order	.jpg,.dng

Asset Scope

Variable	Description
WITH_ARCHIVED	Include archived assets
WITH_DELETED	Include deleted assets
FILTER_ALBUM_IDS	Filter by album names or IDs, comma-separated
FILTER_TAKEN_AFTER	ISO 8601 lower bound
FILTER_TAKEN_BEFORE	ISO 8601 upper bound

Criteria and Logging

Variable	Description
CRITERIA	JSON grouping criteria
LOG_LEVEL	trace, debug, info, warn, error
LOG_FORMAT	text or json
LOG_FILE	Optional dual logging file path

Default Criteria

[
  {
    "key": "originalFileName",
    "split": { "delimiters": ["~", "."], "index": 0 }
  },
  {
    "key": "localDateTime",
    "delta": { "milliseconds": 1000 }
  }
]