narratio/docs/cli.md

# CLI

## Shortest Useful Command

```bash
narratio run --session-id 2026-04-04
```

This command uses default discovery for `pipeline.yml` and `session.yml`; both files must be discoverable unless you pass explicit `--config` and `--session` paths.

## Command Overview

Implemented commands:

- `run`: execute pipeline stages and persist manifest state.
- `plan`: validate config, prepare workspace layout, and print stage run/skip decisions.
- `resume`: continue from first non-succeeded stage unless forced.
- `status`: read and print stage statuses from an existing manifest.
- `run-stage`: execute exactly one stage.
- `restore`: restore durable local session state from the committed remote archive state.

Unknown commands print usage and exit non-zero.

For config semantics, see [docs/config.md](./config.md). For operator lifecycle and recovery, see [docs/operations.md](./operations.md).

## Complete Flag Reference

### `run`

- `--config <path>`: optional explicit `pipeline.yml` path.
- `--session <path>`: optional explicit `session.yml` path.
- `--session-id <value>`: session template variable value.
- `--previous-session-id <value>`: previous-session template variable value.
- `--force`: force stage execution.
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).

### `plan`

- `--config <path>`
- `--session <path>`
- `--session-id <value>`
- `--previous-session-id <value>`
- `--force`

### `resume`

- `--config <path>`
- `--session <path>`
- `--session-id <value>`
- `--previous-session-id <value>`
- `--force`
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).

### `run-stage`

- `--config <path>`
- `--session <path>`
- `--session-id <value>`
- `--previous-session-id <value>`
- `--force`
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
- positional `<stage>`: required stage name.

Valid stage names:

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

### `restore`

- `--config <path>`
- `--session <path>`
- `--session-id <value>`
- `--previous-session-id <value>`
- `--dry-run`: plan restore actions without writing local files.
- `--force`: overwrite local conflicting files with remote archive files.
- `--include-audio`: include durable archived `audio/**` files in restore scope.

### `status`

- `--manifest <path>`: required manifest path.

## Command Reference

### `run`

Purpose:
- Execute configured stages in canonical order.

Syntax:

```bash
narratio run [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>]
```

Success output:
- `narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`

Common failure cases:
- missing default config/session paths when flags omitted.
- invalid template/rendered session mismatch.
- unknown/invalid `--artifacts` value.
- `--artifacts` with unknown configured artifact key.

### `plan`

Purpose:
- Validate config, load secrets (if configured), prepare workdir, and print stage run/skip decisions.

Syntax:

```bash
narratio plan [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--force]
```

Success output includes:
- `narratio plan: workdir prepared at <path>`
- one line per stage (`<stage>: run|skip`)
- `totals: run=<n> skip=<n>`

Common failure cases:
- same config/session discovery and validation failures as `run`.
- secrets directory read failures when `pipeline.secrets.env_dir` is configured.

### `resume`

Purpose:
- Continue from session-manifest stage status.

Syntax:

```bash
narratio resume [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>]
```

Success output:
- `narratio resume: session <session_id> has no remaining stages`
- or `narratio resume: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`

Common failure cases:
- same discovery/template/validation failures as `run`.
- manifest load errors when existing manifest is unreadable.
- invalid or unknown artifact selections.

### `status`

Purpose:
- Inspect one manifest file without executing stages.

Syntax:

```bash
narratio status --manifest <manifest.json>
```

Success output includes:
- `session_id: <id>`
- `updated_at: <timestamp>`
- `stages:` entries (`- <stage>: <status>`)

Common failure cases:
- missing `--manifest`.
- unreadable or invalid manifest path.

### `run-stage`

Purpose:
- Execute exactly one stage.

Syntax:

```bash
narratio run-stage [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>] <stage>
```

Success output:
- `narratio run-stage: stage=<name> executed=<n> skipped=<n> force=<true|false>; manifest=<path>`

`--artifacts` behavior:
- accepted only when `<stage>` is `analyze`.
- names are normalized (trimmed, deduplicated, sorted).
- unknown configured artifact keys fail.

Common failure cases:
- missing stage positional arg.
- unknown stage name.
- using `--artifacts` with any non-`analyze` stage.

### `restore`

Purpose:
- Restore durable session state (`manifest.json`, `transcripts/**`, `artifacts/**`, `previous/**`, and optional `audio/**`) from the committed remote archive current state.

Syntax:

```bash
narratio restore [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--dry-run] [--force] [--include-audio]
```

Success output (dry-run):
- `Restore plan for <campaign>/<session_id>`
- `Remote run: <run_id>`
- `Would download: <n>`
- `Would skip unchanged: <n>`
- `Conflicts: <n>`

Success output (non-dry-run):
- `Restored session archive for <campaign>/<session_id>`
- `Remote run: <run_id>`
- `Downloaded: <n>`
- `Skipped unchanged: <n>`
- `Conflicts: <n>`

Common failure cases:
- storage backend is not configured.
- remote `current/run_id.txt` missing/empty.
- remote `current/manifest.json` missing or invalid.
- remote manifest session/campaign mismatch.
- local conflicts without `--force`.
- session lock conflict.

## Common Workflows

Default-discovery run:

```bash
narratio run --session-id 2026-04-04
```

Run only selected analyze artifacts:

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

Resume with selected analyze artifacts:

```bash
narratio resume --session-id 2026-04-04 --artifacts player_handout
```

Run only analyze stage with selected artifacts:

```bash
narratio run-stage --session-id 2026-04-04 --artifacts player_handout analyze
```

Preview restore actions without writes:

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

Restore and then force analyze:

```bash
narratio restore --session-id 2026-04-04
narratio run-stage --session-id 2026-04-04 --force analyze
```

Rehydrate canonical previous-session inputs after artifact-input changes:

```bash
narratio run-stage --session-id 2026-04-04 --force prepare
```

## Diagnostic / Recovery Commands

Inspect stage status:

```bash
narratio status --manifest <manifest.json>
```

Get manifest path from previous output:
- `run`, `resume`, and `run-stage` print `manifest=<path>` on success.

## `--artifacts` and `--force`

- `--artifacts` filters which configured artifacts are executable when analyze runs.
- `--artifacts` does not imply `--force`.
- if analyze is already `succeeded` and `--force` is not set, runner-level skip still applies.