# runs

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/make/cli/runs/>.

Find previous cuts and films, read their decisions, or render another version. CLI and browser runs share the same history.

In Docker, run these commands from the installation folder with
`docker compose exec immich-memories` before `immich-memories`.

## Find a run

```bash
immich-memories runs list
immich-memories runs list --status failed
immich-memories runs show RUN_ID
```

`show` gives status, scope, output, title source, timing and system details. For a film sent to Immich it adds the delivery state, the album and a link to the video; the output line says when the local copy was removed after delivery. A partial ID works when unambiguous among the 100 most recent runs; use the full ID for older runs.

A run whose process is gone (killed, crashed, machine restarted) reads `interrupted` in `list`, `show` and the browser. A run still going in another terminal stays `running`.

## Read the cut

```bash
immich-memories runs story RUN_ID
immich-memories runs why ASSET_ID --run RUN_ID
```

`story` shows shots in playback order, with timecode, capture date and why each one plays: who is on it, what it shows or where it was taken, and what set it apart (a star, a video, the only frame with someone in it). A story that
joins many places is named by its first two and a count of the rest. `why` shows where one picture was kept or dropped and your current persistent decision about it.

Without an ID, `story` reads the most recent completed run; `why` uses that run unless `--run` selects another. The command reports when a decision log is unavailable.

## runs render

Render a saved cut without selecting pictures again:

```bash
immich-memories runs render RUN_ID
immich-memories runs render RUN_ID --revision 2 --no-music
```

A revision is the version saved from the browser editor. Output options such as resolution, title, music, orientation and upload can change, but the selected pictures stay fixed. Configured title or music services can still be used for the render.

For a film across accounts, the saved cut also keeps the exact file copy and the account that can read it. Moving a favourite to another copy does not change which file a replay uses.

Every render is a new run, with its own id: `runs render` and the browser's **Render** both make one. The finished film goes under `output.directory`. `runs upload` takes that render run's id, not the cut's; on a cut that was never rendered it says so and points back here. Once Immich confirms the upload, `runs upload` removes the local film and says so; a failed or incomplete upload keeps it. A saved cut needs its render inputs to replay; if they are unavailable, make a fresh cut.

To listen to generated music first (requires a generator):

```bash
immich-memories music preview RUN_ID
immich-memories runs render RUN_ID --music TRACK_PATH
```

## Storage and deletion

```bash
immich-memories runs storage --json
immich-memories runs stats
immich-memories runs delete RUN_ID
```

`storage` reports directories under output and cache; loose files directly in those roots are not counted. `stats` summarizes history. `delete` removes the run record and its output; add `--keep-output` to keep the file. Deletion asks for confirmation; use `--yes` for an intentional scripted deletion.

To investigate slowness or failures, use [report](https://sam-dumont.github.io/immich-memories/docs/make/cli/report.md). Every flag: [CLI reference](https://sam-dumont.github.io/immich-memories/docs/reference/cli-reference.md#runs).
