Document the native CLI and migration workflows

This commit is contained in:
2026-11-20 06:41:59 +00:00
parent faa8cb5822
commit 0e9cbc9c2a
16 changed files with 633 additions and 672 deletions

View File

@@ -1,497 +1,449 @@
# 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>`
- `--overlay <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`.
- `--overlay` selects `overlays/<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 overlay 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, Narratio uses the optional
`/usr/local/etc/narratio/secrets` directory.
- `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>] [--overlay <name>] [--secrets-dir <directory>]
narratio config show [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config sources [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config artifacts [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config diff <left-overlay> <right-overlay> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--secrets-dir <directory>]
```
These commands resolve the selected overlay, 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.credentials[]`, 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-overlay (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
overlay and its file, selected campaign, party source, and digest. The
remaining tab-separated records are sorted as `path`, `role`, and `source`.
Roles distinguish root, import, overlay, normalization, centralized default,
campaign, party, and generated family ownership. Records labeled
`resolution` retain their effective pre-normalization source contributors;
superseded definitions remain historical evidence in the artifact catalog.
Records labeled
`empty_import` identify the source-local declaration path, selector, and
location of an optional import that selected no sources. 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, contributing family source files, and party file.
Family source paths are comma-separated when ConfigKit reports a composite
origin. 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 overlay names independently and compares
their fully resolved, secret-free effective mappings. It does
not accept `--overlay`; the two positional names must be distinct, valid
overlays. When party-driven families are present, both overlays must resolve to
the same selected campaign and party. Use `--campaign-file` if overlay-specific
campaign configuration would otherwise select different files.
Equal overlays print `no differences`. Otherwise, sorted tab-separated records
use one of these forms, with compact JSON values:
## Command tree
```text
added <path> <right-value>
removed <path> <left-value>
changed <path> <left-value> <right-value>
narratio
├── run SESSION
├── artifacts
│ ├── list
│ └── regenerate SESSION
├── session
│ ├── init SESSION
│ ├── plan SESSION
│ ├── validate SESSION
│ ├── status SESSION
│ ├── restore SESSION
│ ├── clean [SESSION | --all]
│ ├── artifacts SESSION
│ └── locks
│ ├── list SESSION
│ ├── add SESSION SOURCE
│ └── remove SESSION SOURCE
├── config
│ ├── scopes
│ ├── validate
│ ├── show
│ ├── sources
│ ├── explain
│ └── diff
├── version
├── completion bash|zsh|fish
└── help [COMMAND...]
```
Paths use JSON Pointer notation, with `~0` for `~` and `~1` for `/`. Native
comparison reports a changed mapping region as one value when a whole mapping
is added or removed; lists are compared as whole values. A `hidden_changed=true`
field indicates a change hidden by redaction. The command compares defaulted concrete artifacts and publish rules, not
overlay names, source-file layout, or formatting. It succeeds when differences
are found, making it suitable for review and migration checks.
Bare root and command groups display help. Use `narratio help session plan`
or `narratio session plan --help` for command-local flags and operands. Help,
version, completion, and `config scopes` do not bootstrap credentials, load
configuration, contact storage, or initialize adapters.
### `version`
## Invocation syntax
```bash
narratio version
Place flags after the complete command path; they may be interspersed with
operands there. For example, `narratio session plan --format json SESSION`
and `narratio session plan SESSION --format json` are equivalent. Flags are
local to the selected command. `--` ends option parsing.
Value flags accept `--name value` or `--name=value`. Boolean flags accept
presence as true or an explicit value such as `--force=false`. Repeated
single-value flags use the last successfully parsed value; every occurrence
must parse. Repeatable flags accumulate values. An explicitly supplied empty,
false, or zero value differs from omission. Narratio additionally normalizes
repeatable `--artifacts` values as described below.
## Configuration selectors
| Selector | Meaning |
| --- | --- |
| `--config PATH` | Exact pipeline root, regardless of configuration scope; omission uses discovery. |
| `--overlay NAME` | Pipeline overlay; omitted, empty, or `default` selects the base. |
| `--campaign ID` | Select and assert the effective campaign identity. |
| `--campaign-file PATH` | Exact campaign source; may accompany its identity assertion. |
| `--session ID` | Session identity for native configuration inspection only. |
| `--session-file PATH` | Exact session source; domain commands use positional `SESSION` as the identity assertion. |
| `--party-file PATH` | Select the canonical roster instead of the campaign's default file. |
| `--secrets-dir PATH` | Explicit credential-bootstrap directory. |
| `--previous-session-id ID` | Assert the configured previous-session identity on applicable domain commands. |
Explicit relative file/directory paths use the invocation directory. Explicit
file errors and identity mismatches fail without fallback. A file selects the
source; an identity asserts its effective ID after resolution. File-only
configuration inspection may obtain identity from the file. Selecting a party
file does not rewrite the campaign's party setting; the selected roster feeds
players, family expansion, planning, and execution consistently.
Selectors are installed only where applicable; command help lists them.
`session init` creates new input and therefore has no existing-session-file
or party-file selection. `session clean --all` accepts pipeline/overlay/secrets
selection and rejects campaign, session, party, and previous-session selectors.
When no explicit session file is selected, local discovery precedes remote
acquisition. Only local absence permits remote fallback, with a known identity.
Remote loading prefers authored session-root YAML, then the current commit's
prepared snapshot only when the authored object is absent. Read-only commands
may perform these reads without initializing runtime state. See
[discovery](config.md#discovery-and-selection) and
[credential bootstrap](config.md#secrets-handling) for configuration details.
## Run
```sh
narratio run SESSION
narratio run SESSION --from extract --through analyze
narratio run SESSION --stage analyze --force --artifacts session_recap
```
Official release binaries report their exact Git tag. Binaries built directly
from source without release linker metadata report `dev`.
The default is the full canonical pipeline:
`prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `render`,
`extract`, `analyze`, `publish`, `notify`, `cleanup`.
`--from` and `--through` select inclusive contiguous bounds. `--stage` selects
one stage and cannot accompany explicitly supplied range flags. `--force`
reruns selected work; dependent invalidation can extend beyond that range.
Bounded starts require valid preceding manifest state. Ordinary execution uses
semantic resume checks rather than rerunning all selected work.
### `run`
Analysis-only rebuilding uses `run SESSION --stage analyze --force`; it does
not refresh extraction. Publishing alone uses `run SESSION --stage publish`,
adding `--force` when a rerun is intended. It does not schedule cleanup. See
[operations](operations.md#artifact-development-workflows) for regeneration workflows.
```bash
narratio run <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
## Artifacts regenerate
```sh
narratio artifacts regenerate SESSION
narratio artifacts regenerate SESSION --artifacts session_recap,player_handout
```
Behavior:
Forces the fixed inclusive `extract` through `analyze` range. It refreshes the
whole configured Notarius extraction bundle and chunk work, then selected
analysis targets and required prerequisites. `--artifacts` narrows analysis,
not extraction lanes. Publication, notification, and cleanup are outside this
range. Independent `--from`, `--through`, `--stage`, and `--force` flags are
not installed on this command. It accepts applicable context selectors and
returns the same run report as `run`.
- 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 Notarius credentials 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 overlay (or `none`) and effective configuration digest.
## Artifacts list
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]
```sh
narratio artifacts list --config pipeline.yml --campaign-file campaign.yml
```
Exactly equivalent to:
Lists domain definitions: source identities, producers, outputs, dependencies,
and selected-party family/member provenance. It acquires the context needed to
derive that catalog, without requiring a session solely for listing definitions.
It does not add generated members to native `config show` output.
```bash
narratio run <session_id> --force --from extract --through analyze [caller options]
## Session plan
```sh
narratio session plan SESSION --stage analyze --force --format json
```
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.
Accepts the same stage/range, force, artifact, and context selections as `run`.
Reports execution/reuse actions and reasons, analysis targets, prerequisite work,
and publication mappings through shared planners. Planning reads existing state
without creating a workspace, changing manifests, acquiring execution locks, or
initializing stage adapters. It does not predict unknown output identities.
The forced extraction rebuilds the complete configured Notarius bundle,
disables Notarius checkpoint loading, and requests chunk-plan refresh.
`--artifacts` narrows only the analysis work; it never selects Notarius lanes.
## Session validate
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]
```sh
narratio session validate SESSION --session-file ./session.yml
```
Valid stage names:
Read-only preflight checks configuration and required input, audio,
previous-session, publication, and lock readiness. Material findings remain in
the report regardless of diagnostic visibility. Invalid configuration uses the
native input classification; readiness failures are operational failures.
- `prepare`
- `transcribe`
- `merge`
- `polish`
- `normalize`
- `trim`
- `render`
- `extract`
- `analyze`
- `publish`
- `notify`
- `cleanup`
## Session status
Rules:
- `--artifacts` is accepted only for `analyze` and `publish` stage targets.
### `analyze`
```bash
narratio analyze <session_id> [--artifacts <name[,name...]>] [...common config flags]
```sh
narratio session status SESSION --format json
```
Equivalent to:
Reports local manifest stages and artifacts, configuration provenance, readiness,
and remote current state when storage is available. Remote output entries retain
exact committed declarations and carried-output origins separately from current
configured destinations. An absent remote current pointer is a reported missing
state, rather than an error by itself. Genuine inspection failures can return a
partial report with a failed outcome.
```bash
narratio run-stage analyze <session_id> --force [...common config flags]
## Session artifacts
```sh
narratio session artifacts SESSION --remote
```
This selects only `analyze`: it does not invoke Notarius, replace extraction,
or remove existing extract outputs. `--artifacts` narrows the forced analysis
targets and their required analysis prerequisites.
Reports definitions, dependencies, local availability/evidence, and optional
remote publication state without reading artifact payload bodies. Without
`--remote`, this command avoids remote artifact inspection. Current publication
outcomes include `published`, `carried_locked`, `locked_unpublished`,
`optional_missing`, and `unselected`.
### `publish`
## Session init
```bash
narratio publish <session_id> [--artifacts <name[,name...]>] [...common config flags]
```sh
narratio session init SESSION --output ./session.yml --audio-dir ./audio
narratio session init SESSION --remote --audio-s3-prefix audio/session/
```
Equivalent to:
Choose exactly one destination: `--output PATH` or `--remote`. Options include
`--date YYYY-MM-DD`, `--title TEXT`, `--previous-session-id ID`, `--force`,
configuration/overlay/campaign/secrets selectors, and exactly one audio override
if needed: `--audio-dir PATH` or `--audio-s3-prefix PREFIX`.
```bash
narratio run-stage publish <session_id> --force [...common config flags]
A configured session template retains its import/resource authoring context;
relative CLI audio paths use the invocation directory. Generated YAML is
standalone and concrete. `--format` changes only the confirmation report,
never the generated YAML file. See [initialization](operations.md#session-initialization).
## Session restore
```sh
narratio session restore SESSION --dry-run
narratio session restore SESSION --force --include-audio
```
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.
Uses pointer-selected committed state and returns actions/conflicts. Dry runs
make no local directory or mode changes. Actual restore preserves confined
replacement, transition locking, incomplete-restore recovery markers, and
manifest-last installation. `--force` permits replacement only of eligible
regular files. The public report is separate from the persisted restore
execution report. See [restore operations](operations.md#restore-workflow).
### `clean`
## Session clean
```bash
narratio clean <session_id> [--dry-run] [--clear-cache] [...common config flags]
narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]
```sh
narratio session clean SESSION --dry-run
narratio session clean --all --dry-run --clear-cache
```
Behavior:
Choose positional `SESSION` or `--all`. Removes the selected local workspace
and spool state; cache deletion requires `--clear-cache`. Dry runs return planned
actions without deletion. Partial failures retain completed actions. This manual
operation is separate from the pipeline cleanup stage. Exact scope and recovery
implications belong in [cleanup operations](operations.md#cleanup).
- 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.
## Session locks
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]
```sh
narratio session locks list SESSION
narratio session locks add SESSION narratio.artifact.session_recap --reason 'manual review'
narratio session locks remove SESSION narratio.artifact.session_recap
```
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 overlay (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.
A bare locks group displays help. List reports independent remote locks sorted
by source. Add reports an existing lock unless `--force` requests one
conditional, generation-matched replacement; concurrent change requires retry.
Remove is idempotent. `--reason TEXT` is available on add. See
[publish locks](operations.md#publish-locks) for their publication effect.
### `session validate`
## `--artifacts` selection rules
```bash
narratio session validate <session_id> [...common config flags]
`run`, `session plan`, and `artifacts regenerate` accept repeatable
`--artifacts NAME[,NAME...]`. Values are trimmed, deduplicated, and sorted.
Family keys select all concrete members; concrete keys select one member.
Analysis includes required prerequisite closure. Publication selects applicable
configured artifact outputs. The option requires a selected analysis or publish
consumer and does not select built-in output sources or individual extraction
lanes. See [artifact configuration](config.md#scriptorium-artifact-families).
## Configuration inspection
`config scopes` lists operations and features without loading. The four scopes
are `app` (default), `campaign`, `session`, and `party`. They expose their actual
typed ConfigKit results, with native provenance, resolution history, and safe
secret views. App inspection needs no campaign/party expansion. Domain catalogs
and execution plans are separate views.
```sh
narratio config show --scope app --format json
narratio config show --scope session --session SESSION --session-file ./session.yml
narratio config show --scope party --party-file ./party.yml
narratio config show --path /scriptorium --format yaml
narratio config sources --scope campaign --campaign-file ./campaign.yml
narratio config explain --path /scriptorium --format json
narratio config explain --list --under /scriptorium --historical
narratio config validate --details --severity error
```
Read-only preflight checks for config validity, required inputs, audio mode,
previous-session requirements, publish outputs, and independent remote locks.
- `show` displays safe effective values; `--path POINTER` selects a current
value, including present null. An empty pointer selects the root.
- `sources` lists native source records, imports, placements, version evidence,
and empty optional-import selections. `--source-id ID` selects a record from
that load. Available source evidence can be reported after load failure.
- `explain --path POINTER` reports effective/history fragments, origins,
resolution reasons/dependencies, and safe secret-reference metadata.
`explain --list` discovers paths. `--under POINTER`, `--historical`, and
`--explicit=true|false` filter discovery; they require `--list`. Historical-only
paths do not match an explicitness filter. Neither mode supplied shows help.
- `validate` returns concise status or native structured scope outcomes.
`--details` includes findings; repeatable `--severity error|warning` and
`--code CODE` filter displayed findings, never validation success.
- `--scope all` is supported for show/validate, requiring applicable context for
every reached scope. It is unsupported for sources, explain, and diff.
### `session status`
Paths use JSON Pointer: escape `/` as `~1` and `~` as `~0`. Malformed pointers
fail as usage; a well-formed unknown selected path fails operationally.
Native report fields and detailed source/history semantics are documented in the
[selected CommandKit CLI contract](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/docs/cli.md#configuration-scopes).
```bash
narratio session status <session_id> [...common config flags]
### Independent comparisons and overrides
```sh
narratio config diff --config pipeline.yml --against-config pipeline.yml --against-overlay testing --details --check
narratio config diff --scope party --party-file before.yml --against-party-file after.yml
narratio config show --scope app --set '/whisperx/concurrency=2'
```
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.
Diff loads each side independently. In addition to native `--against-config`
and `--against-overlay`, applicable scopes accept `--against-campaign`,
`--against-campaign-file`, `--against-session`, `--against-session-file`, and
`--against-party-file`. Omitted right-side selectors use their own normal
defaults; they never inherit left-side selections. Each party default follows
that side's campaign.
### `session init`
Concise diff reports `additions`, `changes`, and `deletions`; detailed diff
reports `scope` and `differences` with `path`, `before`, `after`, and
`hidden_changed`. Snapshots distinguish absence, null, and redaction. Comparison
uses effective values rather than source arrangement. Secret changes remain
hidden safely. A diff is inspection output, not a configuration patch.
```bash
narratio session init <session_id> --output ./session.yml [options]
narratio session init <session_id> --remote [options]
Only app inspection supports ordered, repeatable `--set POINTER=JSON`, plus
`--against-set POINTER=JSON` for the comparison side. ConfigKit applies these
during that load. They affect only that invocation. Other scopes and aggregate
inspection reject overrides. Execution/planning use files and overlays;
they have no field-override flags.
## Reporting and visibility
Reports go to stdout; diagnostics and progress go to stderr. Domain commands
return one final public report where useful, including meaningful partial work
on failure. `--format text|yaml|json` selects presentation. Automatic structured
reports use YAML; text uses the same data. Version and native inspection commands
may have native text renderers. Report format does not change artifact formats.
There is no public report schema-version field.
| Category | Ordinary | `--quiet` | `--verbose` | `--debug` |
| --- | --- | --- | --- | --- |
| Final report | Shown | Hidden | Shown | Shown |
| Terminal failure | Shown | Shown | Shown | Shown |
| Info and Warning | Hidden | Hidden | Shown | Shown |
| Debug | Hidden | Hidden | Hidden | Shown |
| Progress by default | Hidden | Hidden | Hidden | Shown |
The last enabled quiet/verbose/debug mode wins. Explicit false clears only the
currently selected matching mode, returning to ordinary mode. There is no mode
stack. Independent `--progress` or `--progress=false` overrides the default;
quiet always suppresses progress. Verbose and progress can be combined.
Progress covers stage transitions/reuse, audio transfers/cache reuse, and
individual durable speaker/artifact checkpoints and validated reuse. Info adds
selected sources, destinations, and decision context. Concurrent completion
order is not fixed. Workers settle before the final report.
Console debug does not enable downstream debug captures or change retention.
Downstream streams stay in captured logs and are not replayed automatically.
Quiet changes visibility, not execution, persistence, or logging. A report or
diagnostic delivery failure can fail the invocation after durable work has
completed; it does not roll back that work.
### Public domain report fields
Optional fields appear when meaningful; these reports do not expose raw
manifests, resolved credentials, or internal dependency containers.
| Report | Fields |
| --- | --- |
| Run/regenerate | `campaign`, `session_id`, `run_id`, `stages`, `executed`, `skipped`, `stage_results`, `available_artifacts`, `artifact_targets`, `complete` |
| Plan | `campaign`, `session_id`, `stages` with `name`, `action`, `reason`, optional `analysis`; `publication_actions` |
| Catalog | `artifacts` with source, producer, output, enabled state, dependencies, optional concrete key and family/member/source provenance |
| Validation | `campaign`, `session_id`, `session_source`, `valid`, `findings` with severity, category, message |
| Status/artifacts | Identities/source, `local_manifest`, `stages`, `artifacts`, optional `remote`, configuration provenance, audio/previous-artifact readiness, `findings` |
| Init | `campaign`, `session_id`, `destination`, `remote`, `written` |
| Locks | Identities, `operation`, `result`, `complete`, optional `source`, `locks` |
| Restore | Identities/run, `dry_run`, `complete`, `status`, `downloaded`, `conflicts`, `actions` |
| Clean | Optional identities, `all`, `dry_run`, `complete`, `cache`, `actions`, optional `error` |
Run `stages` is the complete selection. `executed` includes attempted work,
including failures and self-skips. `skipped` includes reuse and self-skips.
Each `stage_results` entry has `name`, `attempted`, `outcome`
(`completed`, `failed`, `reused`, `skipped`, `not_attempted`), and optional
`reason`. Available artifacts carry `stage`, optional `source`, `kind`, `path`,
optional `producer_run_id`, and durable `evidence` (`stage_result`,
`speaker_checkpoint`, `artifact_checkpoint`). Failed or unpersisted work is not
reported as completed.
Plan analysis contains `targets`, `prerequisites`, `execute`, and `reuse`;
artifact entries identify key, optional family/character, role, reason, and
force. Publication actions identify source, destination, required, and selected.
Remote status outputs retain source, destination, required, state, lock state,
optional outcome, declared destination/key, origin run, and error. Restore
actions carry kind, relative local path, remote key, status, optional reason/error.
Clean actions carry path, status (`would_delete`, `deleted`, `missing`, `empty`,
`failed`), and optional error; cache records whether it was preserved, requested,
processed, or not applicable. Lock rows include source, reason, creation time,
and whether publication is configured for that source.
## Cancellation and exit status
Ctrl-C and termination cancel acquisition and active operations. Narratio stops
scheduling work, waits for started workers, attempts terminal local manifest
persistence, and releases acquired resources. Successful checkpoints remain
resumable. Cancellation does not schedule cleanup. Abrupt process death has no
added finalization guarantee.
| Status | Meaning |
| --- | --- |
| `0` | Success, including ordinary diff with differences. |
| `1` | Operational/readiness failure, cancellation, or output failure. |
| `2` | Invalid invocation or identifiable invalid configuration input. |
| `3` | `config diff --check` found differences. |
Missing/unreadable sources and ambiguous or callback loading failures are
operational; malformed or explicitly rejected configuration input uses native
input classification. Mixed failures preserve underlying causes and operational
precedence. Terminal failure is presented once, including in quiet mode.
## Version and completion
```sh
narratio version --format text
narratio version --scope commandkit --format json
source <(narratio completion bash)
source <(narratio completion zsh)
narratio completion fish | source
```
Required target selection:
Version text is `NAME VERSION` with an optional revision; structured identity
contains `name`, `version`, and `revision`. Development builds without an embedded
version report `dev`. Bash requires bash-completion initialized; Zsh requires
its completion system initialized. Native completion offers command/flag names,
static stage/scope values, and applicable file/directory hints. Dynamic campaign
and artifact completion is deferred.
- exactly one of:
- `--output <path>`
- `--remote`
## Migration from the previous CLI
Options:
Removed command paths have no compatibility aliases.
- `--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`
| Previous invocation | Current invocation |
| --- | --- |
| `run-stage STAGE SESSION` | `run SESSION --stage STAGE` |
| `analyze SESSION` | `run SESSION --stage analyze --force` |
| `publish SESSION` | `run SESSION --stage publish --force` |
| `regenerate-artifacts SESSION` | `artifacts regenerate SESSION` |
| `clean SESSION` / `clean --all` | `session clean SESSION` / `session clean --all` |
| `config artifacts` | `artifacts list` |
| `session locks SESSION` | `session locks list SESSION` |
| `--session FILE` | `--session-file FILE`; inspection `--session` now asserts identity |
| `--session-id ID` | Positional `SESSION` on domain commands; `--session ID` on config inspection |
| `config diff LEFT_OVERLAY RIGHT_OVERLAY` | `config diff --overlay LEFT_OVERLAY --against-overlay RIGHT_OVERLAY` |
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).
- template imports and relative resources resolve in the template's local
authoring context. Generated output contains standalone effective values.
- relative `--audio-dir` paths resolve from the invocation directory.
### `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).
Campaign identity and file selectors may now accompany each other. Party-file
selection consistently overrides the roster without editing campaign settings.
Native configuration inspection retains declarations and their actual evidence;
use catalog/plan/session views for generated domain products. Comparison defaults
are independent. Field overrides are inspection-only. Update scripts to consume
structured reports and exit classifications, place flags after the complete
command path, and account for native repetition and cancellation behavior.