2026-05-23 12:50:46 +00:00
|
|
|
# CLI Reference
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Command tree
|
2026-08-30 15:10:38 +00:00
|
|
|
|
|
|
|
|
```text
|
2026-11-20 06:41:59 +00:00
|
|
|
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...]
|
2026-08-30 15:10:38 +00:00
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
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
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +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-22 22:09:17 -05:00
|
|
|
```
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-11-20 06:41:59 +00: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
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Artifacts list
|
2026-08-29 18:19:54 +00:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
```sh
|
|
|
|
|
narratio artifacts list --config pipeline.yml --campaign-file campaign.yml
|
2026-08-29 18:19:54 +00:00
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +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
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Session plan
|
2026-05-22 22:09:17 -05:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
```sh
|
|
|
|
|
narratio session plan SESSION --stage analyze --force --format json
|
2026-05-22 22:09:17 -05:00
|
|
|
```
|
2026-05-22 11:28:38 -05:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
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
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Session validate
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
```sh
|
|
|
|
|
narratio session validate SESSION --session-file ./session.yml
|
2026-05-22 22:09:17 -05:00
|
|
|
```
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-11-20 06:41:59 +00: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.
|
2026-05-23 12:50:46 +00:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Session status
|
2026-05-23 12:50:46 +00:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
```sh
|
|
|
|
|
narratio session status SESSION --format json
|
2026-05-23 12:50:46 +00:00
|
|
|
```
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-11-20 06:41:59 +00: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.
|
2026-09-05 15:27:08 +00:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Session artifacts
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
```sh
|
|
|
|
|
narratio session artifacts SESSION --remote
|
2026-05-18 22:03:59 -05:00
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +00: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`.
|
2026-08-09 21:41:23 +00:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Session init
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-11-20 06:41:59 +00: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
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +00: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
|
|
|
|
2026-11-20 06:41:59 +00: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).
|
2026-05-21 11:50:20 -05:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Session restore
|
2026-05-21 11:50:20 -05:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
```sh
|
|
|
|
|
narratio session restore SESSION --dry-run
|
|
|
|
|
narratio session restore SESSION --force --include-audio
|
2026-05-21 11:50:20 -05:00
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
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).
|
2026-05-21 11:50:20 -05:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Session clean
|
2026-05-21 11:50:20 -05:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
```sh
|
|
|
|
|
narratio session clean SESSION --dry-run
|
|
|
|
|
narratio session clean --all --dry-run --clear-cache
|
2026-05-21 11:50:20 -05:00
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
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).
|
2026-05-23 12:50:46 +00:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
## Session locks
|
2026-05-23 12:50:46 +00:00
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
```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
|
2026-05-21 23:02:19 -05:00
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
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
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +00: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'
|
2026-05-22 22:09:17 -05:00
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +00:00
|
|
|
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
|
|
|
```
|
|
|
|
|
|
2026-11-20 06:41:59 +00: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.
|