Files
narratio/docs/cli.md

450 lines
22 KiB
Markdown
Raw Normal View History

# CLI Reference
2026-05-18 22:03:59 -05:00
## 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
2026-08-29 23:13:01 +00:00
```
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
```
2026-05-18 22:03:59 -05:00
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`.
2026-08-29 18:19:54 +00:00
## Artifacts list
2026-08-29 18:19:54 +00:00
```sh
narratio artifacts list --config pipeline.yml --campaign-file campaign.yml
2026-08-29 18:19:54 +00:00
```
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.
2026-08-29 18:19:54 +00:00
## 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.
2026-05-18 22:03:59 -05:00
## Session validate
2026-05-18 22:03:59 -05:00
```sh
narratio session validate SESSION --session-file ./session.yml
```
2026-05-18 22:03:59 -05:00
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
```
2026-05-18 22:03:59 -05:00
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
2026-05-18 22:03:59 -05:00
```sh
narratio session artifacts SESSION --remote
2026-05-18 22:03:59 -05:00
```
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
2026-05-18 22:03:59 -05:00
```sh
narratio session init SESSION --output ./session.yml --audio-dir ./audio
narratio session init SESSION --remote --audio-s3-prefix audio/session/
2026-05-18 22:03:59 -05:00
```
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`.
2026-05-18 22:03:59 -05:00
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
2026-05-21 22:48:18 -05:00
```
- `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
2026-05-18 22:03:59 -05:00
```
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.