narratio/docs/cli.md

# CLI

## Shortest Useful Command

```bash
narratio run 2026-04-04
```

This runs the full pipeline for the given session ID using default config discovery and campaign selection.

## Command Overview
Top-level commands:

- `run <session_id>`: execute the pipeline.
- `resume <session_id>`: continue from first non-succeeded stage.
- `run-stage <stage> <session_id>`: execute exactly one stage.
- `analyze <session_id>`: force-rerun analyze stage.
- `publish <session_id>`: force-rerun publish stage.
- `clean <session_id>|--all`: remove local workspace/spool state.
- `session <subcommand>`: session-scoped helper commands.

Session subcommands:

- `session init <session_id>`
- `session plan <session_id>`
- `session validate <session_id>`
- `session status <session_id>`
- `session restore <session_id>`
- `session artifacts <session_id>`
- `session locks <session_id>`
- `session locks add <session_id> <source>`
- `session locks remove <session_id> <source>`

## Common Flags
Most session-aware commands accept:

- `--config <pipeline.yml>`
- `--campaign <id>`
- `--campaign-file <campaign.yml>`
- `--session <session.yml>`
- `--previous-session-id <id>`

`--campaign` and `--campaign-file` are mutually exclusive.

## Command Reference

### `run`

```bash
narratio run <session_id> [--force] [--artifacts <name[,name...]>] [...common flags]
```

Runs stages in canonical order and writes manifest state.

### `resume`

```bash
narratio resume <session_id> [--force] [--artifacts <name[,name...]>] [...common flags]
```

Starts at the first non-succeeded stage from the session manifest.

### `run-stage`

```bash
narratio run-stage <stage> <session_id> [--force] [--artifacts <name[,name...]>] [...common flags]
```

Valid stage names:

- `prepare`
- `transcribe`
- `merge`
- `polish`
- `normalize`
- `trim`
- `analyze`
- `publish`
- `notify`

`--artifacts` is accepted only for `analyze` and `publish`.

### `analyze`

```bash
narratio analyze <session_id> [--artifacts <name[,name...]>] [...common flags]
```

Equivalent to `narratio run-stage analyze <session_id> --force`.

### `publish`

```bash
narratio publish <session_id> [--artifacts <name[,name...]>] [...common flags]
```

Equivalent to `narratio run-stage publish <session_id> --force`.

### `clean`

```bash
narratio clean <session_id> [--dry-run] [--clear-cache] [...common flags]
narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]
```

- session mode deletes `{workspace.root}/work/{campaign}/{session_id}` and `{spool.root}/{campaign}/{session_id}`.
- `--all` deletes all session work and spool children.
- cache is preserved unless `--clear-cache` is passed.

### `session plan`

```bash
narratio session plan <session_id> [--force] [...common flags]
```

Validates config and session inputs, prepares workdir layout, and prints stage run/skip decisions.

### `session validate`

```bash
narratio session validate <session_id> [...common flags]
```

Read-only preflight checks for config, inputs, audio availability, previous-session requirements, publish outputs, and effective locks.

### `session status`

```bash
narratio session status <session_id> [...common flags]
```

Shows local manifest state, remote current state (when storage is configured), published-output availability, and effective locks.

### `session init`

```bash
narratio session init <session_id> --output ./session.yml
narratio session init <session_id> --remote
narratio session init <session_id> --remote --force
```

Flags:

- `--output <path>` or `--remote` (exactly one is required)
- `--previous-session-id <id>`
- `--date <date>`
- `--title <title>`
- `--audio-dir <path>`
- `--audio-s3-prefix <prefix>`
- `--force`
- common config/campaign flags

### `session restore`

```bash
narratio session restore <session_id> [--dry-run] [--force] [--include-audio] [...common flags]
```

Restores durable local session files from committed remote current state.

Default restore scope:

- `manifest.json`
- `transcripts/**`
- `artifacts/**`
- `previous/**` when required by configured previous-session artifact inputs

`audio/**` is restored only when `--include-audio` is set.

### `session artifacts`

```bash
narratio session artifacts <session_id> [--remote] [...common flags]
```

Lists built-in sources, configured artifact sources, previous-session sources, publish output rules, and lock status. With `--remote`, includes remote published-state markers.

### `session locks`

```bash
narratio session locks <session_id> [...common flags]
narratio session locks add <session_id> <source> [--reason <text>] [--force] [...common flags]
narratio session locks remove <session_id> <source> [...common flags]
```

- list mode prints effective locks from static `pipeline.publish.locks` and remote `{session_prefix}/locks.yml`.
- add/remove mutate only the remote lock store.
- static pipeline locks cannot be removed by lock commands.

## `--artifacts` Rules

- accepted on `run`, `resume`, `run-stage`, `analyze`, and `publish`.
- on `run-stage`, only valid for `analyze` and `publish`.
- filters configured analyze artifact execution.
- filters configured `pipeline.publish.outputs` entries for `narratio.artifact.<key>` sources.
- does not suppress built-in transcript/bounds publish outputs.
- does not imply `--force` for `run`, `resume`, or `run-stage`.

## Common Workflows

Run full pipeline:

```bash
narratio run 2026-04-04
```

Run only selected analyze artifacts:

```bash
narratio run 2026-04-04 --artifacts session_recap,player_handout
```

Force analyze only:

```bash
narratio analyze 2026-04-04 --artifacts player_handout
```

Force publish only:

```bash
narratio publish 2026-04-04
```

Restore preview then apply:

```bash
narratio session restore 2026-04-04 --dry-run
narratio session restore 2026-04-04
```