CLI Reference

This page is auto-generated from the Click command definitions. Run make docs-cli to regenerate.

Global options

Flag	Type	Default	Description
`--version`	boolean	false	Show the version and exit.
`--config`, `-c`	path	-	Path to config file
`--preset`	choice: `fast`	-	Config preset for this run: fast = CPU-only/NAS profile (1080p h264, medium quality, fast encoder preset, static title backgrounds). It changes nothing about what the editor reads. Anything you set explicitly wins
`--verbose`, `-v`	boolean	false	Log at DEBUG level. Shorthand for --log-level DEBUG
`--log-level`	choice: `DEBUG` \| `INFO` \| `WARNING` \| `ERROR`	-	Log level for this run (default: IMMICH_MEMORIES_LOG_LEVEL or INFO)

`auto`

Automation -- detect and generate memory candidates.

immich-memories auto [OPTIONS] COMMAND [ARGS]...

`auto history`

Show recent auto-generated memories.

immich-memories auto history [OPTIONS]

Flag	Type	Default	Description
`--limit`	integer	10	Number of entries to show

`auto install`

Install system-level scheduler (launchd/systemd/cron).

immich-memories auto install [OPTIONS]

Flag	Type	Default	Description
`--hour`	integer range	9	Hour to run (0-23)
`--minute`	integer range	0	Minute to run (0-59)
`--cooldown`	integer	24	Cooldown hours between runs
`--uninstall`	boolean	false	Remove installed scheduler
`--show`	boolean	false	Show config without installing
`--force`	boolean	false	Schedule this install even when its checkout is a worktree or behind its upstream

`auto run`

Generate the chosen eligible candidate, or the highest-scoring one.

immich-memories auto run [OPTIONS]

Flag	Type	Default	Description
`--candidate`	text	-	Exact memory_key from auto suggest --json
`--dry-run`	boolean	false	Show what would be generated
`--force`	boolean	false	Skip cooldown check
`--cooldown`	integer	-	Min hours since last auto-run
`--upload`	boolean	false	Upload to Immich
`--quiet`	boolean	false	One machine-readable line per decision, no progress display; -v adds log detail

`auto status`

Show durable automation and external scheduler state.

immich-memories auto status [OPTIONS]

Flag	Type	Default	Description
`--json`	boolean	false	Machine-readable output

`auto suggest`

Show prioritized memory candidates.

immich-memories auto suggest [OPTIONS]

Flag	Type	Default	Description
`--json`	boolean	false	Machine-readable output
`--limit`	integer	10	Max candidates to show
`--type`	text	-	Filter by memory type

`auto test-notification`

Send a test notification to verify Apprise URL configuration.

immich-memories auto test-notification [OPTIONS]

`capabilities`

Show what this setup supports, what is missing, and which music profiles work.

Connection and installation checks are labelled separately from real generation. Saved settings and running model servers are left alone. Use --test-music after unloading idle models if you want to test music with their memory freed.

immich-memories capabilities [OPTIONS]

Flag	Type	Default	Description
`--test-music`	boolean	false	Generate 15 seconds for each local ACE-Step profile that fits; may download models.
`--verify-local`	boolean	false	Verify configured owned reader and cached local audio with synthetic inputs; no full-film certification
`--json`	boolean	false	Print the report as JSON

`config`

Configure the Immich connection, or inspect where each setting comes from.

Without a subcommand this sets the Immich URL and API key, prompting for them when no option is given. Settings saved here go to the database, below environment variables and config.yaml, which this never writes. The API key is a secret: saving it needs IMMICH_MEMORIES_SECRET_KEY.

immich-memories config [OPTIONS] [COMMAND] [ARGS]...

Flag	Type	Default	Description
`--url`, `-u`	text	-	Immich server URL
`--api-key`, `-k`	text	-	Immich API key
`--show`, `-s`	boolean	false	Same as `config show`

`config move-to-db`

Move settings out of config.yaml into the database.

KEYS are runtime paths such as llm.model (no advanced. prefix). Each value is saved to the database, then its line is removed from config.yaml, so the UI can edit it. The rest of the file keeps its values and ${VAR} references but loses its comments; the old file is kept as config.yaml.bak. Nothing moves without this command.

immich-memories config move-to-db [OPTIONS] KEYS...

Arguments:

keys (text; required, repeatable)

`config show`

Every setting with its value and source: env, file, database or default.

Secrets are masked. An env or file source names the variable or the config.yaml key that sets it. Give key prefixes (llm, immich.url) to show only those.

immich-memories config show [OPTIONS] [PREFIXES]...

Arguments:

prefixes (text; optional, repeatable)

`config test`

Check the Immich connection and the API version it resolves (read-only).

Every extra account under immich.accounts is checked too, one line each.

immich-memories config test [OPTIONS]

`days-due`

Show which discovered days have an anniversary about now.

immich-memories days-due [OPTIONS]

Flag	Type	Default	Description
`--on`	datetime	-	The date to look around (default today)

`days-export`

Write the special-days catalogue as JSON, for a backup or a hand edit.

immich-memories days-export [OPTIONS]

Flag	Type	Default	Description
`--to`	file	-	Write to this file instead of standard output

`days-import`

Replace the special-days catalogue with a JSON file's.

Every record is kept as written, so an edited export comes back exactly. A file whose records do not read as a catalogue changes nothing.

immich-memories days-import [OPTIONS]

Flag	Type	Default	Description
`--from`	file	-	A JSON catalogue, as days-export writes it (required)

`discover-days`

Find days something happened on, and remember them for later.

Meant to run occasionally rather than per generation: the point of a catalogue is a memory nobody asked for (five years to the day since the wedding), and that needs the days found in advance.

Days inside a trip are skipped, since a trip memory already tells that story. On Basic and GPU tiers, holidays spent at home are skipped too. Other days count when one recorded fact stands out (away from home, three favourites, mostly video, or a long day with close family), and each year keeps its strongest few. On Full tier, days are read a month at a time. A separate occasion on a holiday can qualify; the holiday celebration itself belongs to a holiday memory.

Resumes by default: years already in the catalogue are not scanned again, which matters for a command that runs for hours. --rescan starts over.

--replace re-scans the years between --since and --until and replaces their catalogue rows with the newly qualifying days. It says how many rows it will replace before it starts, and it never touches a year outside the period.

The catalogue lives in the store; days-export writes it to a file.

immich-memories discover-days [OPTIONS]

Flag	Type	Default	Description
`--since`	integer	2007	First year to scan
`--until`	integer	current year	Last year to scan
`--also-skip`	text	-	A holiday name or MM-DD this library keeps that the defaults miss (repeatable)
`--rescan`	boolean	false	Start over, ignoring and replacing the existing catalogue
`--replace`	boolean	false	Re-scan --since..--until and replace every row those years already hold, dropping days that no longer qualify. Rows outside the period are kept.

`generate`

Generate a video compilation.

Memory type presets:
  --memory-type season --season summer --year 2024
  --memory-type person_spotlight --person "Riley" --year 2024
  --memory-type multi_person --person "Riley" --person "Bob" --year 2024
  --memory-type multi_person --person "Riley" --person "Bob"   (no dates: from
      the first day both could be in a picture, read off their birth dates)
  --memory-type monthly_highlights --month 7 --year 2024
  --memory-type on_this_day

Manual time period options:
  --year 2024                    Calendar year
  --year 2024 --birthday 02-07   Birthday-based year
  --start 2024-01-01 --end 2024-06-30   Custom range
  --start 2024-01-01 --period 6m        Period from start

immich-memories generate [OPTIONS]

Flag	Type	Default	Description
`--year`, `-y`	integer	-	Year to generate video for (calendar year by default)
`--start`	text	-	Start date (YYYY-MM-DD)
`--end`	text	-	End date (use with --start)
`--period`	text	-	Period from start date (e.g., 6m, 1y, 2w)
`--birthday`, `-b`	text	-	Run the year up to a birthday, plus earlier birthdays (reads Immich's birth date, or override with MM-DD, e.g. 03-15)
`--from-album`	text	-	Generate from an Immich album (name or ID) instead of a date range
`--subject`	text	-	With --from-album: what the album was curated for, in your words. Every picture then stands on that subject, a loaf in a bread album included, and every year the album holds gets a shot. Needs a model reader
`--ask`	text	-	Highly experimental: the film in a sentence, e.g. "our cat along the years". Read by the configured model reader against your prepared library; the translation is printed first. Needs tier: full
`--ask-trace`	file	-	With --ask: keep the translation (the trace, the pool counts, the rule preview, the verdict) in this JSON file, for a watcher such as the web client
`--person`, `-p`	text	-	Person name, or a UUID for exactly one person (repeatable) (repeatable)
`--people-expression`	text	-	Grouped people condition, e.g. ("Person A" OR "Person B") AND "Person C". Use exact library names; read per picture: every named person must be recognised on the same picture, not just somewhere nearby.
`--group`	text	-	A label saved with `people group add`, resolved like --people-expression (mutually exclusive with it, --person and --person-match)
`--person-match`	choice: `and` \| `or`	and	With several --person values, require everyone recognised on the same picture (and) or accept any named person on it (or)
`--accounts`	text	-	Immich accounts the film reads, comma-separated: primary plus names under immich.accounts, e.g. primary,partner. Default: the primary alone
`--memory-type`	choice: `year_in_review` \| `season` \| `person_spotlight` \| `multi_person` \| `monthly_highlights` \| `on_this_day` \| `album` \| `trip` \| `holiday` \| `special_day`	-	Memory type preset (album takes its pool from --from-album)
`--holiday`	text	-	Holiday name or MM-DD (use with --memory-type holiday)
`--season`	choice: `spring` \| `summer` \| `fall` \| `autumn` \| `winter`	-	Season (use with --memory-type season)
`--month`	integer	-	Month 1-12 (with --year, generates that month; selects trip by month)
`--hemisphere`	choice: `north` \| `south`	north	Hemisphere for season calculation
`--duration`, `-d`	integer	-	Target duration in seconds (default: fitted to the material the period holds)
`--short-form`	choice: `15` \| `30` \| `60` \| `90`	-	Short-form preset: sets the duration and makes the video vertical
`--orientation`	choice: `landscape` \| `portrait` \| `square` \| `auto`	auto	Output orientation (auto follows the final selected cut)
`--scale-mode`, `-s`	choice: `fit` \| `blur`	-	How to fill an aspect mismatch: blurred background or black bars (default: from config, else blur)
`--fade-color`	choice: `white` \| `black`	-	Opening and closing title fade (default: title_screens.fade_color)
`--transition`, `-t`	choice: `smart` \| `cut` \| `crossfade` \| `none`	smart	Transition style (default: smart, a mix of fades and cuts)
`--resolution`, `-r`	choice: `auto` \| `4k` \| `1080p` \| `720p`	-	Output resolution (default: config value, 'auto' to match source clips)
`--music-volume`	float	0.5	Music volume 0.0-1.0 (default: 0.5)
`--format`	choice: `mp4` \| `h265` \| `prores`	-	Output format override (default: config value)
`--quality`, `-q`	choice: `high` \| `medium` \| `low`	-	Output quality: high, medium (balanced), low (fast); default: from config
`--output`, `-o`, `-O`	path	-	Output file path. The run writes it inside its own directory and adds a recipe hash to the name; each rerun gets a new run directory
`--music`, `-m`	text	-	Music: path to audio file, 'auto' to generate from config, or omit for default behavior
`--no-music`	boolean	false	Disable all music (skip both provided files and AI generation)
`--dry-run`	boolean	false	Discover inputs and show preparation needs without selection or generation
`--no-render`	boolean	false	Run story-first selection and its audience and media checks, then stop before encoding. Unlike --dry-run, this picks the clips it would actually ship
`--trace-selection`	file	-	Write a stage-by-stage report of how the clips were chosen
`--include`	text	-	Keep this picture in the cut even if the editor would drop it (repeatable) (repeatable)
`--exclude`	text	-	Leave this picture out of the cut (repeatable) (repeatable)
`--sharing`	choice: `just-us` \| `family` \| `shareable`	-	Who the film is for: just-us (the household), family (default: defaults.sharing) or shareable (anyone)
`--upload-to-immich`	boolean	false	Upload generated video back to Immich
`--album`	text	-	Immich album name for uploaded video
`--add-date`, `--no-add-date`	boolean	-	Caption each clip with its date (default: defaults.add_date, on)
`--add-place`, `--no-add-place`	boolean	-	Caption each clip with its place (default: defaults.add_place, on)
`--keep-intermediates`	boolean	false	Keep intermediate files for debugging
`--privacy-mode`	boolean	false	Demo mode: blur every clip frame, scramble the audio, fake the person names
`--title`	text	-	Override video title text
`--llm-title`, `--no-llm-title`	boolean	-	People and occasion memories are named by the model whenever a reader is configured. --llm-title adds trips, --no-llm-title pins the template everywhere (--title still wins)
`--subtitle`	text	-	Override video subtitle text
`--include-live-photos`, `--no-live-photos`	boolean	-	Include Live Photo video clips (3s iPhone clips, merged when burst-captured)
`--include-photos`, `--no-photos`	boolean	-	Include photos as animated Ken Burns clips (blur background, face-aware pan)
`--accept-any-provenance`	boolean	false	Keep forwarded and re-encoded media for this memory; date, person, privacy, and Live Photo boundaries still apply
`--photo-duration`	float	-	Duration per photo clip in seconds (default: 4.0)
`--trip-index`	integer	-	Select a specific trip by index (use with --memory-type trip)
`--all-trips`	boolean	false	Generate a video for every detected trip (use with --memory-type trip)
`--years-back`	integer	-	Years to look back for --birthday, on_this_day or holiday
`--near-date`	text	-	Select trip closest to this date (YYYY-MM-DD, use with --memory-type trip)
`--event-id`	text	-	Exact catalogue event ID (use with --memory-type special_day and --day)
`--day`	datetime	-	The day this memory is about (YYYY-MM-DD). With --memory-type special_day it names a catalogued day, whose title comes from the catalogue rather than from here (`immich-memories days-due` lists them). With --memory-type on_this_day it is the anniversary to look back from, so the cut is reproducible; without it, today
`--quiet`	boolean	false	Silence the live progress display and print log lines instead (cron, logs); -v sets the log level

`hardware`

Show hardware acceleration information.

immich-memories hardware [OPTIONS]

`models`

Fetch the pinned model artifacts selection needs.

immich-memories models [OPTIONS] COMMAND [ARGS]...

`models fetch`

Download every pinned model artifact a first cut needs, in one command.

immich-memories models fetch [OPTIONS]

Flag	Type	Default	Description
`--force`	boolean	false	Re-download even when the file is already right
`--detectors`, `--no-detectors`	boolean	-	Fetch detector models (default: gpu/full only); --detectors also fetches on nas
`--laya`	boolean	false	Fetch the Laya audience checkpoint even on the basic tier (gpu and full fetch it anyway)

`music`

Music and audio commands.

immich-memories music [OPTIONS] COMMAND [ARGS]...

`music add`

Add background music to a video with automatic ducking.

Without a music file, picks a track from your library by --mood (calm when absent). No frame of the video is sent to any model. Music volume is automatically lowered when speech/sounds are detected.

immich-memories music add [OPTIONS] VIDEO_PATH OUTPUT_PATH

Flag	Type	Default	Description
`--music`, `-m`	path	-	Music file (auto-select if not provided)
`--mood`	text	-	Override mood for music selection
`--genre`, `-g`	text	-	Override genre for music selection
`--volume`, `-v`	float	-6.0	Music volume in dB
`--fade-in`	float	2.0	Fade in duration in seconds
`--fade-out`	float	3.0	Fade out duration in seconds

Arguments:

video_path (path; required)
output_path (path; required)

`music preview`

Generate the music this cut would get, from its own timeline and mood, before rendering.

The track it prints renders with runs render RUN --music PATH.

immich-memories music preview [OPTIONS] [RUN_ID]

Flag	Type	Default	Description
`--out`	directory	-	Where to write the track (default: the cache, beside the run)
`--progress-file`	file	-	Keep generation progress in this JSON file, for a watcher such as the web client

Arguments:

run_id (text; optional)

`music search`

Search for music in local library.

immich-memories music search [OPTIONS]

Flag	Type	Default	Description
`--mood`, `-m`	text	-	Mood (happy, calm, energetic, etc.)
`--genre`, `-g`	text	-	Genre (acoustic, electronic, cinematic, etc.)
`--tempo`, `-t`	choice: `slow` \| `medium` \| `fast`	-	Tempo
`--min-duration`	float	60	Minimum duration in seconds
`--limit`, `-n`	integer	10	Number of results

`people`

Who is in this library, and who they are to each other.

Called on its own this still lists the people Immich knows, which is what immich-memories people has always done.

immich-memories people [OPTIONS] [COMMAND] [ARGS]...

`people bind`

Say that one person has this id in another Immich account.

PERSON is a store person id or a name exactly one person carries. The binding only adds the id: the name, birth date and everything you confirmed stay as they are. An id somebody else holds is refused, never merged, and binding the same id again changes nothing.

immich-memories people bind [OPTIONS] PERSON

Flag	Type	Default	Description
`--account`	text	-	The account that reads the id: primary, or an extra account's name (required)
`--id`	text	-	The person's id as that account's Immich knows them (required)

Arguments:

person (text; required)

`people export`

Write the people registry out as YAML, in the shape people.yaml had.

The file holds names and birth dates, so it is created readable by you alone. Edit it and bring it back with people import.

immich-memories people export [OPTIONS]

Flag	Type	Default	Description
`--to`	file	-	Write the YAML here instead of to standard output

`people group`

Saved people expressions generate --group can reuse.

immich-memories people group [OPTIONS] COMMAND [ARGS]...

`people group add`

Save EXPRESSION under LABEL, in the --people-expression grammar.

EXPRESSION's leaves are canonical person ids : the ids people show lists : not names, e.g. ("id-alex" OR "id-sam") AND "id-kit". LABEL must not already be in use.

immich-memories people group add [OPTIONS] LABEL EXPRESSION

Arguments:

label (text; required)
expression (text; required)

`people group list`

List every saved group and its expression.

immich-memories people group list [OPTIONS]

`people group rm`

Remove a saved group. Never touches the people it names.

immich-memories people group rm [OPTIONS] LABEL

Arguments:

label (text; required)

`people import`

Replace the people registry with a YAML file, keeping every id as written.

The whole file is checked first; if any person in it is malformed, nothing is written and every problem is listed. A registry that already holds people is only overwritten with --replace.

immich-memories people import [OPTIONS]

Flag	Type	Default	Description
`--from`	file	-	A YAML file written by `people export` (or an old people.yaml) (required)
`--replace`	boolean	false	Overwrite a registry that already holds people

`people scan`

Build or refresh the people registry from Immich.

Reads every named person's count and month curve, then asks about each remaining pair to find who appears with whom. Nothing here looks at a pixel and nothing here asks you a question: the library's own distribution is the whole input.

Safe to re-run: everything you confirmed is copied through untouched, and preferred to this pass's reading forever after.

immich-memories people scan [OPTIONS]

Flag	Type	Default	Description
`--min-assets`	integer	25	Pictures a named person needs before the graph has an opinion
`--owner`	text	-	The name of the person whose library this is, if the account does not say

`people show`

Print the people registry: what the last scan read and what you confirmed.

immich-memories people show [OPTIONS]

Flag	Type	Default	Description
`--tier`	choice: `inner` \| `recurring` \| `episodic` \| `event`	-	Show only one tier

`pictures`

Your own word on a picture: clear its hold, or never use it.

Every tier reads it, in every later cut. Find the asset id at the end of the picture's Immich URL: /photos/ASSET_ID.

immich-memories pictures [OPTIONS] COMMAND [ARGS]...

`pictures clear-hold`

Clear this one picture's hold for a level, after you've looked at it yourself.

immich-memories pictures clear-hold [OPTIONS] ASSET_ID

Flag	Type	Default	Description
`--level`	choice: `anyone` \| `family` \| `just-us`	-	The widest film it may play in; asked when not given (--yes: family)
`--yes`	boolean	false	Clear it without asking

Arguments:

asset_id (text; required)

`pictures list`

Every picture you cleared or will never use.

immich-memories pictures list [OPTIONS]

`pictures never-use`

Keep this picture out of every film from now on.

immich-memories pictures never-use [OPTIONS] ASSET_ID

Arguments:

asset_id (text; required)

`pictures show`

What holds this picture, and what you decided.

immich-memories pictures show [OPTIONS] ASSET_ID

Arguments:

asset_id (text; required)

`pictures undo`

Forget what you decided about this picture: the app's own holds apply again.

immich-memories pictures undo [OPTIONS] ASSET_ID

Arguments:

asset_id (text; required)

`preflight`

Run preflight checks to validate all provider connections.

Checks:

Immich server connection and API key, and each extra account
LLM availability (Ollama or OpenAI-compatible)
Title rendering (GPU or PIL fallback)
Pinned DINOv2 encoder export (presence and digest)
Caption endpoint (advertises the accepted alias)
Configured paths that are not on this host
Notification delivery health
Hardware acceleration

immich-memories preflight [OPTIONS]

Flag	Type	Default	Description
`--verbose`, `-v`	boolean	false	Show detailed output

`prepare`

Prepare a scope's annotations, print what each producer cost, and stop.

# No selection and no render happen. Preparation is banked per picture, so
# a scope prepared today is free for every later cut:
  immich-memories prepare --year 2024 --month 6
  immich-memories prepare --start 2024-01-01 --period 1y
#
# --overviews goes one step further and banks what each month was about,
# which a cut of that month then reads instead of working it out again:
  immich-memories prepare --year 2024 --month 6 --overviews

immich-memories prepare [OPTIONS]

Flag	Type	Default	Description
`--year`, `-y`	integer	-	Calendar year to prepare
`--month`	integer	-	Month 1-12, with --year: one month at a time
`--start`	text	-	Start date (YYYY-MM-DD)
`--end`	text	-	End date (use with --start)
`--period`	text	-	Period from the start date (e.g. 6m, 1y, 2w)
`--overviews`	boolean	false	Also bank each month's episode readings and the account a cut reads as its thesis
`--library-size`	integer	1000	Project the measured rate onto a library of this many pictures

`report`

Print a privacy-safe GitHub issue report. Defaults to the latest run.

Logs are included. Review the report before sharing it. Nothing is sent.

immich-memories report [OPTIONS] [RUN_ID]

Flag	Type	Default	Description
`--json`	boolean	false	Print the redacted report as JSON
`--bundle`	file	-	Write the full redacted report to a ZIP file
`--include-flagged-captions`	boolean	false	Include captions and reasons of flagged free-text photos; review before sharing
`--wrong`	text	-	Mark a photo of a free-text film as wrong (repeatable); kept on the run (repeatable)
`--missing`	text	-	Say what a free-text film is missing; kept on the run and checked against it

Arguments:

run_id (text; optional)

`runs`

Browse and manage pipeline run history.

immich-memories runs [OPTIONS] COMMAND [ARGS]...

`runs delete`

Delete a run and optionally its output files.

Examples:

# Delete run and its output
immich-memories runs delete 20260105_143052_a7b3

# Delete run but keep the video
immich-memories runs delete 20260105_143052_a7b3 --keep-output

immich-memories runs delete [OPTIONS] RUN_ID

Flag	Type	Default	Description
`--keep-output`	boolean	false	Keep the output video file
`--yes`	boolean	false	Confirm the action without prompting.

Arguments:

run_id (text; required)

`runs list`

List recent pipeline runs.

Examples:

# List recent runs
immich-memories runs list

# Filter by person
immich-memories runs list --person "John"

# Show only failed runs
immich-memories runs list --status failed

immich-memories runs list [OPTIONS]

Flag	Type	Default	Description
`--limit`, `-n`	integer	20	Number of runs to show
`--person`, `-p`	text	-	Filter by person name
`--status`, `-s`	choice: `completed` \| `failed` \| `running` \| `cancelled` \| `interrupted`	-	Filter by status

`runs render`

Render a finished cut, or one of its saved revisions, through the same engine as generate.

With no RUN_ID the most recent completed run is rendered. Revisions are the ones the web client saved (--revision 2); without one, the cut renders as it was chosen.

immich-memories runs render [OPTIONS] [RUN_ID]

Flag	Type	Default	Description
`--revision`	integer	-	Render this saved revision of the cut
`--title`	text	-	Title card text (default: as generate decides)
`--subtitle`	text	-	Title card subtitle
`--llm-title`, `--no-llm-title`	boolean	-	Let the model name the film
`--transition`	choice: `smart` \| `crossfade` \| `cut` \| `none`	-	Transition style (default: saved cut)
`--fade-color`	choice: `white` \| `black`	-	Opening and closing title fade (default: title_screens.fade_color)
`--title-style`	choice: `auto` \| `random` \| `modern_warm` \| `elegant_minimal` \| `vintage_charm` \| `playful_bright` \| `soft_romantic`	-	Title style for this render (default: title_screens.style_mode)
`--resolution`	choice: `auto` \| `4k` \| `1080p` \| `720p`	-	Output resolution (default: from config)
`--orientation`	choice: `landscape` \| `portrait` \| `square` \| `auto`	-	Output orientation (default: auto, follows the saved cut)
`--scale-mode`	choice: `fit` \| `blur`	-	Fill an aspect mismatch with black bars or a blurred background
`--format`	choice: `mp4` \| `h265` \| `prores`	-	Output format override, as generate takes it (default: config value)
`--quality`	choice: `high` \| `medium` \| `low`	-	Output quality: high, medium (balanced), low (fast); default: from config
`--music`	text	-	A track to use, or 'auto' to choose as configured
`--no-music`	boolean	false	Render without a music track
`--music-volume`	float	0.5	Music volume from 0.0 to 1.0
`--add-date`, `--no-add-date`	boolean	-	Caption each clip with its date (default: defaults.add_date, on)
`--add-place`, `--no-add-place`	boolean	-	Caption each clip with its place (default: defaults.add_place, on)
`--privacy-mode`	boolean	false	Demo mode: blur every clip frame, scramble the audio, fake the person names
`--upload-to-immich`	boolean	false	Upload the film to Immich after rendering
`--album`	text	-	Immich album for the upload
`--progress-file`	file	-	Keep the render's progress in this JSON file, for a watcher such as the web client

Arguments:

run_id (text; optional)

`runs show`

Show detailed information about a specific run.

Example: immich-memories runs show 20260105_143052_a7b3

immich-memories runs show [OPTIONS] RUN_ID

Arguments:

run_id (text; required)

`runs stats`

Show aggregate statistics across all runs.

immich-memories runs stats [OPTIONS]

`runs storage`

Report configured output and cache storage without changing it.

immich-memories runs storage [OPTIONS]

Flag	Type	Default	Description
`--json`	boolean	false	Machine-readable output

`runs story`

Print the cut of a run in the order it plays: day, kind, length, story, reason.

With no RUN_ID the most recent completed run is read. A run id prefix works, and so does the path of an attempt directory.

immich-memories runs story [OPTIONS] [RUN_ID]

Arguments:

run_id (text; optional)

`runs why`

Say what a run decided about one picture: where it passed, where it was dropped, and why.

immich-memories runs why [OPTIONS] ASSET_ID

Flag	Type	Default	Description
`--run`	text	-	Run id or prefix (default: latest)

Arguments:

asset_id (text; required)

`store`

The database that holds your decisions, model answers, run history and settings.

SQLite at ~/.immich-memories/store.db unless IMMICH_MEMORIES_DATABASE_URL (or database.url) names another one. Stop the app before restore.

immich-memories store [OPTIONS] COMMAND [ARGS]...

`store backup`

Write a consistent backup while the app runs, with a manifest beside it.

SQLite: VACUUM INTO. PostgreSQL: pg_dump of the schema in custom format, which needs the PostgreSQL client tools on PATH.

immich-memories store backup [OPTIONS]

Flag	Type	Default	Description
`--to`	file	-	The backup file (default: ~/.immich-memories/backups/store-UTCTIME.db, .dump on PostgreSQL)

`store copy`

Copy every table into another store: SQLite to PostgreSQL, or back.

The target is migrated first, and every table's row count and content digest are compared afterwards. Point IMMICH_MEMORIES_DATABASE_URL at the target to switch.

immich-memories store copy [OPTIONS]

Flag	Type	Default	Description
`--to`	text	-	The database URL to copy into (required)
`--schema`	text	-	The PostgreSQL schema to copy into (default: the configured one)
`--force`	boolean	false	Empty a target that already holds rows

`store facts`

Inspect detector compatibility and plan selective refreshes.

immich-memories store facts [OPTIONS] COMMAND [ARGS]...

`store facts migrate`

Carry compatible Marqo still facts forward without inference; keep old versions.

immich-memories store facts migrate [OPTIONS]

Flag	Type	Default	Description
`--apply`	boolean	false	Apply the compatible migration; default only reports it
`--json`	boolean	false	Print the migration report as JSON

`store facts refresh`

Plan a selective detector refresh; --apply removes only those facts, all versions.

Stop preparation workers first. Run prepare for the affected scope afterwards. Captions, pixel measurements, other detectors and owner decisions stay banked.

immich-memories store facts refresh [OPTIONS]

Flag	Type	Default	Description
`--head`	text	-	Detector to refresh; repeat for multiple heads (required, repeatable)
`--asset`	text	-	Asset ID to refresh; repeat for multiple assets (required, repeatable)
`--apply`	boolean	false	Forget the selected facts; default only reports them
`--json`	boolean	false	Print the selected refresh as JSON

`store facts status`

Show banked producer versions; an app upgrade alone does not invalidate them.

immich-memories store facts status [OPTIONS]

Flag	Type	Default	Description
`--json`	boolean	false	Print machine-readable compatibility counts

`store import`

Bring the files the app used before the store into it.

Safe to run again: a record the store holds is never replaced, and an importer whose files have not changed since it last completed is skipped. An interrupted import finishes where it stopped.

immich-memories store import [OPTIONS]

Flag	Type	Default	Description
`--from`	directory	-	The directory holding the legacy files (default: IMMICH_MEMORIES_IMPORT_FROM, then database.import_from, then ~/.immich-memories). They are only read, never changed
`--verify`	boolean	false	Afterwards, check that every legacy record is in the store with equal values; exit 1 on any difference

`store migrate`

Upgrade the store to this app's schema without starting a film.

immich-memories store migrate [OPTIONS]

`store restore`

Replace the store with a backup, migrate it to head and check its row counts.

Stop the app first: a restore cannot reach another process's connections.

immich-memories store restore [OPTIONS]

Flag	Type	Default	Description
`--from`	file	-	A file `store backup` wrote; its manifest must sit beside it (required)
`--force`	boolean	false	Replace a store that already holds rows

`store status`

Backend, URL, schema, revision, import record, row counts and size.

immich-memories store status [OPTIONS]

`titles`

Title screen generation and testing commands.

immich-memories titles [OPTIONS] COMMAND [ARGS]...

`titles fonts`

Manage title screen fonts.

Five OFL-1.1 families and Noto Sans (Latin, Greek, Cyrillic, Vietnamese) ship inside the wheel. --install adds the Noto faces for every other script a title can hold (Arabic, Hebrew, Indic, Thai, CJK and more) from raw.githubusercontent.com, each file checked against a pinned SHA-256. It is the only step that downloads a font; a render never does. The Docker image runs it at build time.

immich-memories titles fonts [OPTIONS]

Flag	Type	Default	Description
`--install`	boolean	false	Download the pinned Noto script fonts (about 43 MB, most of it CJK)
`--clear`	boolean	false	Clear ~/.immich-memories/fonts
`--list`	boolean	false	List title fonts (the default)

`titles test`

Generate a test title screen to preview styles.

Examples:

# Simple year title
immich-memories titles test --year 2024

# Birthday title with person name
immich-memories titles test --birthday-age 1 --person "Emma"

# Month divider
immich-memories titles test --month 6 --year 2024 --type month

# Portrait orientation (for social media)
immich-memories titles test --year 2024 --orientation portrait

# French locale with specific style
immich-memories titles test --year 2024 --locale fr --style vintage_charm

immich-memories titles test [OPTIONS]

Flag	Type	Default	Description
`--year`, `-y`	integer	-	Year for title screen (e.g., 2024)
`--birthday-age`	integer	-	Age for birthday title (e.g., 1 for '1st Year')
`--person`, `-p`	text	-	Person name for subtitle
`--month`, `-m`	integer	-	Month for month divider (1-12)
`--orientation`	choice: `landscape` \| `portrait` \| `square`	landscape	Output orientation
`--resolution`, `-r`	choice: `720p` \| `1080p` \| `4k`	1080p	Output resolution
`--locale`, `-l`	choice: `en` \| `fr` \| `nl` \| `de` \| `es` \| `it` \| `pt-BR` \| `pt-PT` \| `pl` \| `sv` \| `ru` \| `ja` \| `zh-Hans` \| `ko`	en	Language
`--style`, `-s`	choice: `modern_warm` \| `elegant_minimal` \| `vintage_charm` \| `playful_bright` \| `soft_romantic` \| `random`	random	Visual style
`--output`, `-o`, `-O`	path	-	Output file path
`--type`	choice: `title` \| `month` \| `ending`	title	Screen type
`--no-animated-background`	boolean	false	Disable animated backgrounds (static gradient)

`ui`

Launch the web client: make, review, refine and render memories in the browser.

immich-memories ui [OPTIONS]

Flag	Type	Default	Description
`--port`, `-p`	integer	-	Port to run the UI on (default: config or 8080)
`--host`, `-h`	text	-	Host to bind to (default: config or 127.0.0.1)
`--reload`, `--no-reload`	boolean	false	Enable hot reload (for development only)

`years`

List years with video content.

immich-memories years [OPTIONS]

Global options​

auto​

auto history​

auto install​

auto run​

auto status​

auto suggest​

auto test-notification​

capabilities​

config​

config move-to-db​

config show​

config test​

days-due​

days-export​

days-import​

discover-days​

generate​

hardware​

models​

models fetch​

music​

music add​

music preview​

music search​

people​

people bind​

people export​

people group​

people group add​

people group list​

people group rm​

people import​

people scan​

people show​

pictures​

pictures clear-hold​

pictures list​

pictures never-use​

pictures show​

pictures undo​

preflight​

prepare​

report​

runs​

runs delete​

runs list​

runs render​

runs show​

runs stats​

runs storage​

runs story​

runs why​

store​

store backup​

store copy​

store facts​

store facts migrate​

store facts refresh​

store facts status​

store import​

store migrate​

store restore​

store status​

titles​

titles fonts​

titles test​

ui​

years​

Global options

`auto`

`auto history`

`auto install`

`auto run`

`auto status`

`auto suggest`

`auto test-notification`

`capabilities`

`config`

`config move-to-db`

`config show`

`config test`

`days-due`

`days-export`

`days-import`

`discover-days`

`generate`

`hardware`

`models`

`models fetch`

`music`

`music add`

`music preview`

`music search`

`people`

`people bind`

`people export`

`people group`

`people group add`

`people group list`

`people group rm`

`people import`

`people scan`

`people show`

`pictures`

`pictures clear-hold`

`pictures list`

`pictures never-use`

`pictures show`

`pictures undo`

`preflight`

`prepare`

`report`

`runs`

`runs delete`

`runs list`

`runs render`

`runs show`

`runs stats`

`runs storage`

`runs story`

`runs why`

`store`

`store backup`

`store copy`

`store facts`

`store facts migrate`

`store facts refresh`

`store facts status`

`store import`

`store migrate`

`store restore`

`store status`

`titles`

`titles fonts`

`titles test`

`ui`

`years`