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
showdisplays safe effective values;--path POINTERselects a current value, including present null. An empty pointer selects the root.sourceslists native source records, imports, placements, version evidence, and empty optional-import selections.--source-id IDselects a record from that load. Available source evidence can be reported after load failure.explain --path POINTERreports effective/history fragments, origins, resolution reasons/dependencies, and safe secret-reference metadata.explain --listdiscovers paths.--under POINTER,--historical, and--explicit=true|falsefilter discovery; they require--list. Historical-only paths do not match an explicitness filter. Neither mode supplied shows help.validatereturns concise status or native structured scope outcomes.--detailsincludes findings; repeatable--severity error|warningand--code CODEfilter displayed findings, never validation success.--scope allis 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.