# CLI Reference ## Command tree ```text 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...] ``` 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. ## Invocation syntax 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 ``` 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. 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. ## Artifacts regenerate ```sh narratio artifacts regenerate SESSION narratio artifacts regenerate SESSION --artifacts session_recap,player_handout ``` 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`. ## Artifacts list ```sh narratio artifacts list --config pipeline.yml --campaign-file campaign.yml ``` 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. ## Session plan ```sh narratio session plan SESSION --stage analyze --force --format json ``` 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. ## Session validate ```sh narratio session validate SESSION --session-file ./session.yml ``` 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. ## Session status ```sh narratio session status SESSION --format json ``` 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. ## Session artifacts ```sh narratio session artifacts SESSION --remote ``` 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`. ## Session init ```sh narratio session init SESSION --output ./session.yml --audio-dir ./audio narratio session init SESSION --remote --audio-s3-prefix audio/session/ ``` 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`. 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 ``` 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). ## Session clean ```sh narratio session clean SESSION --dry-run narratio session clean --all --dry-run --clear-cache ``` 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 locks ```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 ``` 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. ## `--artifacts` selection rules `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 ``` - `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. 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). ### 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' ``` 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. 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. 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 ``` 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. ## Migration from the previous CLI Removed command paths have no compatibility aliases. | 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` | 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.