# 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:

- `version`: print the Narratio build version.
- `run <session_id>`: run all or one contiguous range of the canonical stage order.
- `regenerate-artifacts <session_id>`: force-run extraction through analysis.
- `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.
- `config <subcommand>`: validate or display resolved pipeline configuration.

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>`
- `--profile <name>`

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.
- `--previous-session-id` is a strict expectation: the selected session file
  must contain the same `previous_session_id`.
- `--profile` selects a declared pipeline profile. It may be supplied once;
  an explicit empty or unknown value fails configuration resolution. When it is
  omitted, a declared `default_profile` is used. The same selection applies to
  all common-flag commands, including `regenerate-artifacts`.
- `clean --all` cannot be combined with campaign/session selectors.
- notification delivery is currently limited to the configured `noop` mode; see
  the [configuration reference](./config.md#notifications).

## 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

### `config validate`, `config show`, and `config sources`

```bash
narratio config validate [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]
narratio config show [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]
narratio config sources [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]
```

These commands resolve the selected profile, defaults, ordinary paths, and—if
a campaign is selected—the campaign-owned party. They neither discover or load
a session nor create a workspace, manifest, run, lock, adapter, remote
connection, or credential environment.

Campaign selection is optional for a pipeline without party-driven artifact
families. A pipeline with `scriptorium.artifact_families` needs a selected or
configured default campaign so Narratio can expand its concrete artifacts and
publish rules. `--campaign` and `--campaign-file` remain mutually exclusive.
Session, range, force, and artifact-execution flags are not accepted.

`config validate` writes a concise root-path, selected-profile (or `none`), and
effective-digest summary after successful complete validation. `config show`
writes one deterministic, secret-free YAML document containing defaulted and
expanded concrete configuration. It omits composition declarations, artifact
family declarations, and runtime provenance.

`config sources` reports the same fully validated resolution without printing
effective values. Its header identifies the root, ordered imports, selected
profile and overlay, selected campaign, party mode/source, and digest. The
remaining tab-separated records are sorted as `path`, `role`, and `source`.
Roles distinguish root, import, profile, centralized default, campaign, party,
legacy-player, and generated family ownership. A generated party member has
one family record and one party record at the same logical path. The output
never reads or prints secret values.

### `version`

```bash
narratio version
```

Official release binaries report their exact Git tag. Binaries built directly
from source without release linker metadata report `dev`.

### `run`

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

Behavior:

- evaluates one inclusive contiguous range of the canonical stage order;
- defaults an omitted `--from` to `prepare` and an omitted `--through` to
  `notify`, so omitting both retains full-pipeline behavior;
- rejects unknown endpoints and a `--from` endpoint after `--through`;
- runs `render` before `extract`; an omitted or disabled Notarius
  configuration records an explicit `notarius_disabled` self-skip;
- skips already-succeeded stages unless `--force` is set or a stage-specific
  resume check finds its durable result obsolete;
- applies `--force` only to stages in the selected range;
- rejects repeated `--from`, `--through`, or `--force` options, including
  `--name=value` spellings;
- continues interrupted or partially completed sessions by running non-succeeded stages;
- writes session and run manifests.
- reports the resolved profile (or `none`) and effective configuration digest.

When `--artifacts` is present, the selected range must contain `analyze` or
`publish`. Either consumer is sufficient, including a one-stage range.

### `regenerate-artifacts`

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

Exactly equivalent to:

```bash
narratio run <session_id> --force --from extract --through analyze [caller options]
```

The command always reruns extraction. Analysis rebuilds the selected configured
artifacts and any prerequisites required by those targets; without
`--artifacts`, it uses the normal default analysis selection. Publish and notify
never run. Common session/configuration options and repeatable artifact values
pass through unchanged.

Because the expansion owns `--force`, `--from`, and `--through`, callers cannot
supply those options. The shared `run` parser reports them as duplicate
singleton flags. The alias has no private execution options or behavior, and
runtime diagnostics may identify the operation as `run`.

### `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`
- `extract`
- `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 the selected session's local work and spool state;
- `--all` removes all local session work and spool state;
- cache remains unless `--clear-cache` is provided.

See [Operations: Cleanup](./operations.md#cleanup) for deletion scope and
post-publish cleanup behavior.

### `session plan`

```bash
narratio session plan <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
```

Uses the same inclusive bounds, endpoint validation, force scope, and artifact
selection contract as `run`. It validates config and prints run/skip decisions
for selected stages only without creating the local workdir or changing the
manifest. Resume-capable selected stages are checked against durable evidence.
The output includes the resolved profile (or `none`) and effective configuration
digest without writing provenance or any manifest state.
For `analyze`, the preview also lists explicit targets, prerequisite-only work,
execution order, and reusable current artifacts with concise reasons. These
artifact decisions come from the same reconciliation and work planner used by
execution; the preview does not predict output identities.

### `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, status for the
pointer-selected remote commit and its declared published outputs.

### `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 an execution report;
- blocks unresolved conflicts. `--force` permits replacement only of eligible
  regular files.

See [Operations: Restore Workflow](./operations.md#restore-workflow) for the
default restore scope, report location, and conflict-handling workflow.

### `session artifacts`

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

Lists effective built-in, configured Scriptorium, and configured extraction
sources; reports planned, available, unavailable, and published state without
reading payload bodies; and includes 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 reports the effective merge of static and remote locks;
- add/remove mutate only remote locks;
- static locks from pipeline config cannot be removed by CLI commands.

See [Operations: Publish Locks](./operations.md#publish-locks) for lock storage
and precedence.

## `--artifacts` Selection Rules

An artifact-family key selects all of its concrete character members. A
concrete generated key selects only that member; mixed family and concrete
selection is deduplicated and executed as concrete keys. The resulting plan
and command output identify both the concrete key and, where applicable, its
family and character ID.

- accepted on `run`, `session plan`, `run-stage`, `analyze`, and `publish`;
- repeatable and comma-separated values are combined, surrounding whitespace
  is removed, and duplicate names are collapsed;
- names must exist in `pipeline.scriptorium.artifacts`;
- empty entries are invalid;
- on `run-stage`, only `analyze` and `publish` accept the option.

Effects:

- selects explicit analyze targets; required configured prerequisites may be
  reused or rebuilt before them;
- filters publish rules that source `narratio.artifact.<name>`;
- does not filter built-in transcript/bounds or explicitly configured
  `narratio.extraction.<name>` publish sources; and
- does not select or filter Notarius lanes.

## 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
```

Regenerate post-transcript artifacts without publishing:

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

## Output And Exit Behavior

- Successful commands write their result or summary to standard output and
  exit with status `0`.
- Command failures and invalid invocations write an error to standard error and
  exit with status `1`.
- An unknown top-level command also prints the top-level usage summary to
  standard error.
- `session restore --help` prints its command-specific usage and exits with
  status `0`.

Output is intended for operator inspection. Narratio does not currently offer
a machine-readable CLI output mode; durable machine-readable state is recorded
in manifests and reports described in [Operations](./operations.md).