narratio/docs/cli.md

# 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, display, source-trace, catalog, or compare 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>`
- `--secrets-dir <directory>`

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 `profiles/<name>.yml` relative to the pipeline root. It
  may be supplied once; omitted, empty, and the exact name `default` select the
  base configuration, while an unknown named profile fails. The same selection
  applies to all common-flag commands, including `regenerate-artifacts`.
- `--secrets-dir` selects ConfigKit credential-file bootstrap explicitly. A
  relative value uses caller CWD. Without the flag, a present `secrets/`
  directory beside the resolved root pipeline is used; an absent one is skipped.
- `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`, `config sources`, `config artifacts`, and `config diff`

```bash
narratio config validate [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>] [--secrets-dir <directory>]
narratio config show [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>] [--secrets-dir <directory>]
narratio config sources [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>] [--secrets-dir <directory>]
narratio config artifacts [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>] [--secrets-dir <directory>]
narratio config diff <left-profile> <right-profile> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--secrets-dir <directory>]
```

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, or remote
connection. Like every pipeline-loading command, they bootstrap the selected or
conventional secrets directory before resolving configuration; `config show`
never includes bootstrap reports or secret values in its YAML output.
Typed credential references, including `notarius.llm_api_key`, must therefore
resolve even though these inspection commands never construct an adapter.

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 ConfigKit directives, 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 source, and digest. The
remaining tab-separated records are sorted as `path`, `role`, and `source`.
Roles distinguish root, import, profile, centralized default, campaign, party,
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.

`config artifacts` prints the concrete catalog used by analysis, ordered by
artifact key. Its tab-separated header is `key`, `source`, `definitions`,
`enabled`, `output`, `dependencies`, `family`, `character`, `family_source`, and
`party_source`. Definitions and effective dependencies are sorted comma-separated
lists, and control characters in fields are escaped. Family-member rows identify
their family, character, defining family file, and party file. An empty catalog
prints only the header. Ordinary artifacts can be inspected without a campaign;
party-driven families retain the campaign requirement. See
[Scriptorium Artifact Entries](./config.md#scriptorium-artifact-entries) for the
configuration layout.

`config diff` resolves both supplied profile names independently and compares
their fully resolved, secret-free effective mappings. It does
not accept `--profile`; the two positional names must be distinct, declared
profiles. When party-driven families are present, both profiles must resolve to
the same selected campaign and party. Use `--campaign-file` if profile-specific
campaign configuration would otherwise select different files.

Equal profiles print `no differences`. Otherwise, sorted tab-separated records
use one of these forms, with compact JSON values:

```text
added    <path>    <right-value>
removed  <path>    <left-value>
changed  <path>    <left-value>    <right-value>
```

Mappings are flattened to their logical field paths; lists remain one atomic
value. The command compares defaulted concrete artifacts and publish rules, not
profile names, source-file layout, or formatting. It succeeds when differences
are found, making it suitable for review and migration checks.

### `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
  `cleanup`, 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;
- resolves every selected typed credential during the initial configuration
  load, including a Notarius credential when extract is disabled, outside the
  selected range, or later skipped as resumable;
- 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 the session manifest as the sole durable progress ledger. Each
  invocation also creates its run-local directory and returns an immediate
  command summary; neither creates another durable progress record.
- 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`
- `cleanup`

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

This command selects only `publish`; it does not invoke cleanup. Use a normal
full run to include configured cleanup, or `run-stage cleanup` to retry cleanup
from valid publication evidence.

### `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 manual and pipeline-stage
deletion scope.

### `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 independent remote 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. Current
publish metadata reports `published`, `carried_locked`, `locked_unpublished`,
`optional_missing`, and `unselected`; carried output lines include the run
derived from their exact declared key, the key itself, and its declared
destination. A separately displayed `dest` is the destination requested by the
current configuration and may differ while an older declaration is locked.

### `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>`
- `--secrets-dir <directory>`
- `--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. Remote inspection uses exact commit
declarations and displays the five current publish outcomes when recorded.

### `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 validates and reports independent remote locks sorted by source;
- add creates one lock and reports an existing lock unless `--force` is used;
- `--force` performs one generation-matched replacement and reports a
  concurrent change for operator retry; and
- remove is idempotent and reports when the source was not locked.

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

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