Files
narratio/docs/cli.md

22 KiB

CLI Reference

Command tree

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 and credential bootstrap for configuration details.

Run

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 for regeneration workflows.

Artifacts regenerate

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

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

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

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

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

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

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.

Session restore

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.

Session clean

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.

Session locks

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

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.

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.

Independent comparisons and overrides

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

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.