# CLI Reference

## Shortest Useful Command

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

This runs the canonical full pipeline for session `2026-04-04`.

## Command Overview

Top-level commands:

- `run <session_id>`: run full stage order.
- `run-stage <stage> <session_id>`: run one stage.
- `analyze <session_id>`: force-run analyze.
- `publish <session_id>`: force-run publish.
- `clean <session_id>` or `clean --all`: remove local work/spool state.
- `session <subcommand>`: session 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 Config Flags

Most session-aware commands accept:

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

Rules:

- `--campaign` and `--campaign-file` are mutually exclusive.
- `--session` is not used by `session init`.
- if both positional `<session_id>` and `--session-id` are provided, values must match.
- `clean --all` cannot be combined with campaign/session selectors.

## Session ID Input Rules

Session-aware commands accept one of these forms:

- positional session ID: `... <session_id>`
- compatibility flag: `... --session-id <session_id>`

When both are present, command parsing requires an exact match.

Commands with additional positionals keep their command-specific order:

- `run-stage <stage> <session_id>` or `run-stage <stage> --session-id <session_id>`
- `session locks add <session_id> <source>` or `session locks add --session-id <session_id> <source>`
- `session locks remove <session_id> <source>` or `session locks remove --session-id <session_id> <source>`

## Command Reference

### `run`

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

Behavior:

- evaluates full stage order;
- skips already-succeeded stages unless `--force` is set;
- continues interrupted or partially completed sessions by running non-succeeded stages;
- writes session and run manifests.

### `run-stage`

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

Valid stage names:

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

Rules:

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

### `analyze`

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

Equivalent to:

```bash
narratio run-stage analyze <session_id> --force [...common config flags]
```

### `publish`

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

Equivalent to:

```bash
narratio run-stage publish <session_id> --force [...common config flags]
```

### `clean`

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

Behavior:

- session mode removes:
  - `{workspace.root}/work/{campaign}/{session_id}`
  - `{spool.root}/{campaign}/{session_id}`
- `--all` removes:
  - `{workspace.root}/work/*`
  - direct children under `{spool.root}`
- cache remains unless `--clear-cache` is provided.

### `session plan`

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

Validates config, prepares local workdir layout, and prints run/skip decisions for each stage.

### `session validate`

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

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

### `session status`

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

Prints local manifest state and, when storage is available, remote current-state and published-output status.

### `session init`

```bash
narratio session init <session_id> --output ./session.yml [options]
narratio session init <session_id> --remote [options]
```

Required target selection:

- exactly one of:
  - `--output <path>`
  - `--remote`

Options:

- `--config <pipeline.yml>`
- `--campaign <id>` or `--campaign-file <campaign.yml>`
- `--previous-session-id <id>`
- `--date <YYYY-MM-DD>`
- `--title <text>`
- `--audio-dir <path>`
- `--audio-s3-prefix <prefix>`
- `--force`

Rules:

- `--audio-dir` and `--audio-s3-prefix` are mutually exclusive.
- if campaign `session_template_file` is configured, `session init` renders it.
- generated session YAML must be concrete (no unresolved `{{ ... }}` placeholders).

### `session restore`

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

Behavior:

- discovers committed remote current state;
- plans local restores;
- writes `reports/restore-latest.json` on execution;
- blocks conflicting overwrites unless `--force` is set.

Default restore scope:

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

`audio/**` is included only with `--include-audio`.

### `session artifacts`

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

Lists effective built-in and configured artifact sources, publish rules, lock state, and optional remote published-state availability.

### `session locks`

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

Behavior:

- list mode merges static `pipeline.publish.locks` with remote `{session_prefix}/locks.yml`;
- add/remove mutate only remote locks;
- static locks from pipeline config cannot be removed by CLI commands.

## `--artifacts` Selection Rules

- accepted on `run`, `run-stage`, `analyze`, and `publish`;
- names must exist in `pipeline.scriptorium.artifacts`;
- empty entries are invalid;
- repeated names are deduplicated.

Effects:

- filters analyze execution to selected configured artifacts;
- filters publish rules that source `narratio.artifact.<name>`;
- does not filter built-in transcript/bounds publish sources.

## Common Workflows

Run full pipeline:

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

Dry-run restore plan:

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

Generate a concrete session file from template/default structure:

```bash
narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"
```

Force publish only:

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