Document the native CLI and migration workflows
This commit is contained in:
820
docs/cli.md
820
docs/cli.md
@@ -1,497 +1,449 @@
|
||||
# CLI Reference
|
||||
|
||||
## Shortest Useful Command
|
||||
|
||||
```bash
|
||||
narratio run 2026-04-04
|
||||
```
|
||||
|
||||
This runs the canonical full pipeline for session `2026-04-04`.
|
||||
|
||||
## Command Overview
|
||||
|
||||
Top-level commands:
|
||||
|
||||
- `version`: print the Narratio build version.
|
||||
- `run <session_id>`: run all or one contiguous range of the canonical stage order.
|
||||
- `regenerate-artifacts <session_id>`: force-run extraction through analysis.
|
||||
- `run-stage <stage> <session_id>`: run one stage.
|
||||
- `analyze <session_id>`: force-run analyze.
|
||||
- `publish <session_id>`: force-run publish.
|
||||
- `clean <session_id>` or `clean --all`: remove local work/spool state.
|
||||
- `session <subcommand>`: session helper commands.
|
||||
- `config <subcommand>`: validate, display, source-trace, catalog, or compare resolved pipeline configuration.
|
||||
|
||||
Session subcommands:
|
||||
|
||||
- `session init <session_id>`
|
||||
- `session plan <session_id>`
|
||||
- `session validate <session_id>`
|
||||
- `session status <session_id>`
|
||||
- `session restore <session_id>`
|
||||
- `session artifacts <session_id>`
|
||||
- `session locks <session_id>`
|
||||
- `session locks add <session_id> <source>`
|
||||
- `session locks remove <session_id> <source>`
|
||||
|
||||
## Common Config Flags
|
||||
|
||||
Most session-aware commands accept:
|
||||
|
||||
- `--config <pipeline.yml>`
|
||||
- `--campaign <id>`
|
||||
- `--campaign-file <campaign.yml>`
|
||||
- `--session <session.yml>`
|
||||
- `--session-id <session_id>`
|
||||
- `--previous-session-id <session_id>`
|
||||
- `--overlay <name>`
|
||||
- `--secrets-dir <directory>`
|
||||
|
||||
Rules:
|
||||
|
||||
- `--campaign` and `--campaign-file` are mutually exclusive.
|
||||
- `--session` is not used by `session init`.
|
||||
- if both positional `<session_id>` and `--session-id` are provided, values must match.
|
||||
- `--previous-session-id` is a strict expectation: the selected session file
|
||||
must contain the same `previous_session_id`.
|
||||
- `--overlay` selects `overlays/<name>.yml` relative to the pipeline root. It
|
||||
may be supplied once; omitted, empty, and the exact name `default` select the
|
||||
base configuration, while an unknown named overlay fails. The same selection
|
||||
applies to all common-flag commands, including `regenerate-artifacts`.
|
||||
- `--secrets-dir` selects ConfigKit credential-file bootstrap explicitly. A
|
||||
relative value uses caller CWD. Without the flag, Narratio uses the optional
|
||||
`/usr/local/etc/narratio/secrets` directory.
|
||||
- `clean --all` cannot be combined with campaign/session selectors.
|
||||
- notification delivery is currently limited to the configured `noop` mode; see
|
||||
the [configuration reference](./config.md#notifications).
|
||||
|
||||
## Session ID Input Rules
|
||||
|
||||
Session-aware commands accept one of these forms:
|
||||
|
||||
- positional session ID: `... <session_id>`
|
||||
- compatibility flag: `... --session-id <session_id>`
|
||||
|
||||
When both are present, command parsing requires an exact match.
|
||||
|
||||
Commands with additional positionals keep their command-specific order:
|
||||
|
||||
- `run-stage <stage> <session_id>` or `run-stage <stage> --session-id <session_id>`
|
||||
- `session locks add <session_id> <source>` or `session locks add --session-id <session_id> <source>`
|
||||
- `session locks remove <session_id> <source>` or `session locks remove --session-id <session_id> <source>`
|
||||
|
||||
## Command Reference
|
||||
|
||||
### `config validate`, `config show`, `config sources`, `config artifacts`, and `config diff`
|
||||
|
||||
```bash
|
||||
narratio config validate [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
|
||||
narratio config show [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
|
||||
narratio config sources [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
|
||||
narratio config artifacts [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
|
||||
narratio config diff <left-overlay> <right-overlay> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--secrets-dir <directory>]
|
||||
```
|
||||
|
||||
These commands resolve the selected overlay, defaults, ordinary paths, and—if
|
||||
a campaign is selected—the campaign-owned party. They neither discover or load
|
||||
a session nor create a workspace, manifest, run, lock, adapter, or remote
|
||||
connection. Like every pipeline-loading command, they bootstrap the selected or
|
||||
conventional secrets directory before resolving configuration; `config show`
|
||||
never includes bootstrap reports or secret values in its YAML output.
|
||||
Typed credential references, including `notarius.credentials[]`, must therefore
|
||||
resolve even though these inspection commands never construct an adapter.
|
||||
|
||||
Campaign selection is optional for a pipeline without party-driven artifact
|
||||
families. A pipeline with `scriptorium.artifact_families` needs a selected or
|
||||
configured default campaign so Narratio can expand its concrete artifacts and
|
||||
publish rules. `--campaign` and `--campaign-file` remain mutually exclusive.
|
||||
Session, range, force, and artifact-execution flags are not accepted.
|
||||
|
||||
`config validate` writes a concise root-path, selected-overlay (or `none`), and
|
||||
effective-digest summary after successful complete validation. `config show`
|
||||
writes one deterministic, secret-free YAML document containing defaulted and
|
||||
expanded concrete configuration. It omits ConfigKit directives, artifact
|
||||
family declarations, and runtime provenance.
|
||||
|
||||
`config sources` reports the same fully validated resolution without printing
|
||||
effective values. Its header identifies the root, ordered imports, selected
|
||||
overlay and its file, selected campaign, party source, and digest. The
|
||||
remaining tab-separated records are sorted as `path`, `role`, and `source`.
|
||||
Roles distinguish root, import, overlay, normalization, centralized default,
|
||||
campaign, party, and generated family ownership. Records labeled
|
||||
`resolution` retain their effective pre-normalization source contributors;
|
||||
superseded definitions remain historical evidence in the artifact catalog.
|
||||
Records labeled
|
||||
`empty_import` identify the source-local declaration path, selector, and
|
||||
location of an optional import that selected no sources. A generated party member has
|
||||
one family record and one party record at the same logical path. The output
|
||||
never reads or prints secret values.
|
||||
|
||||
`config artifacts` prints the concrete catalog used by analysis, ordered by
|
||||
artifact key. Its tab-separated header is `key`, `source`, `definitions`,
|
||||
`enabled`, `output`, `dependencies`, `family`, `character`, `family_source`, and
|
||||
`party_source`. Definitions and effective dependencies are sorted comma-separated
|
||||
lists, and control characters in fields are escaped. Family-member rows identify
|
||||
their family, character, contributing family source files, and party file.
|
||||
Family source paths are comma-separated when ConfigKit reports a composite
|
||||
origin. An empty catalog prints only the header. Ordinary artifacts can be
|
||||
inspected without a campaign; party-driven families retain the campaign
|
||||
requirement. See
|
||||
[Scriptorium Artifact Entries](./config.md#scriptorium-artifact-entries) for the
|
||||
configuration layout.
|
||||
|
||||
`config diff` resolves both supplied overlay names independently and compares
|
||||
their fully resolved, secret-free effective mappings. It does
|
||||
not accept `--overlay`; the two positional names must be distinct, valid
|
||||
overlays. When party-driven families are present, both overlays must resolve to
|
||||
the same selected campaign and party. Use `--campaign-file` if overlay-specific
|
||||
campaign configuration would otherwise select different files.
|
||||
|
||||
Equal overlays print `no differences`. Otherwise, sorted tab-separated records
|
||||
use one of these forms, with compact JSON values:
|
||||
## Command tree
|
||||
|
||||
```text
|
||||
added <path> <right-value>
|
||||
removed <path> <left-value>
|
||||
changed <path> <left-value> <right-value>
|
||||
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...]
|
||||
```
|
||||
|
||||
Paths use JSON Pointer notation, with `~0` for `~` and `~1` for `/`. Native
|
||||
comparison reports a changed mapping region as one value when a whole mapping
|
||||
is added or removed; lists are compared as whole values. A `hidden_changed=true`
|
||||
field indicates a change hidden by redaction. The command compares defaulted concrete artifacts and publish rules, not
|
||||
overlay names, source-file layout, or formatting. It succeeds when differences
|
||||
are found, making it suitable for review and migration checks.
|
||||
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.
|
||||
|
||||
### `version`
|
||||
## Invocation syntax
|
||||
|
||||
```bash
|
||||
narratio version
|
||||
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
|
||||
```
|
||||
|
||||
Official release binaries report their exact Git tag. Binaries built directly
|
||||
from source without release linker metadata report `dev`.
|
||||
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.
|
||||
|
||||
### `run`
|
||||
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.
|
||||
|
||||
```bash
|
||||
narratio run <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
|
||||
## Artifacts regenerate
|
||||
|
||||
```sh
|
||||
narratio artifacts regenerate SESSION
|
||||
narratio artifacts regenerate SESSION --artifacts session_recap,player_handout
|
||||
```
|
||||
|
||||
Behavior:
|
||||
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`.
|
||||
|
||||
- evaluates one inclusive contiguous range of the canonical stage order;
|
||||
- defaults an omitted `--from` to `prepare` and an omitted `--through` to
|
||||
`cleanup`, so omitting both retains full-pipeline behavior;
|
||||
- rejects unknown endpoints and a `--from` endpoint after `--through`;
|
||||
- runs `render` before `extract`; an omitted or disabled Notarius
|
||||
configuration records an explicit `notarius_disabled` self-skip;
|
||||
- resolves every selected typed credential during the initial configuration
|
||||
load, including Notarius credentials when extract is disabled, outside the
|
||||
selected range, or later skipped as resumable;
|
||||
- skips already-succeeded stages unless `--force` is set or a stage-specific
|
||||
resume check finds its durable result obsolete;
|
||||
- applies `--force` only to stages in the selected range;
|
||||
- rejects repeated `--from`, `--through`, or `--force` options, including
|
||||
`--name=value` spellings;
|
||||
- continues interrupted or partially completed sessions by running non-succeeded stages;
|
||||
- writes the session manifest as the sole durable progress ledger. Each
|
||||
invocation also creates its run-local directory and returns an immediate
|
||||
command summary; neither creates another durable progress record.
|
||||
- reports the resolved overlay (or `none`) and effective configuration digest.
|
||||
## Artifacts list
|
||||
|
||||
When `--artifacts` is present, the selected range must contain `analyze` or
|
||||
`publish`. Either consumer is sufficient, including a one-stage range.
|
||||
|
||||
### `regenerate-artifacts`
|
||||
|
||||
```bash
|
||||
narratio regenerate-artifacts <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
||||
```sh
|
||||
narratio artifacts list --config pipeline.yml --campaign-file campaign.yml
|
||||
```
|
||||
|
||||
Exactly equivalent to:
|
||||
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.
|
||||
|
||||
```bash
|
||||
narratio run <session_id> --force --from extract --through analyze [caller options]
|
||||
## Session plan
|
||||
|
||||
```sh
|
||||
narratio session plan SESSION --stage analyze --force --format json
|
||||
```
|
||||
|
||||
The command always reruns extraction. Analysis rebuilds the selected configured
|
||||
artifacts and any prerequisites required by those targets; without
|
||||
`--artifacts`, it uses the normal default analysis selection. Publish and notify
|
||||
never run. Common session/configuration options and repeatable artifact values
|
||||
pass through unchanged.
|
||||
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.
|
||||
|
||||
The forced extraction rebuilds the complete configured Notarius bundle,
|
||||
disables Notarius checkpoint loading, and requests chunk-plan refresh.
|
||||
`--artifacts` narrows only the analysis work; it never selects Notarius lanes.
|
||||
## Session validate
|
||||
|
||||
Because the expansion owns `--force`, `--from`, and `--through`, callers cannot
|
||||
supply those options. The shared `run` parser reports them as duplicate
|
||||
singleton flags. The alias has no private execution options or behavior, and
|
||||
runtime diagnostics may identify the operation as `run`.
|
||||
|
||||
### `run-stage`
|
||||
|
||||
```bash
|
||||
narratio run-stage <stage> <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
|
||||
```sh
|
||||
narratio session validate SESSION --session-file ./session.yml
|
||||
```
|
||||
|
||||
Valid stage names:
|
||||
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.
|
||||
|
||||
- `prepare`
|
||||
- `transcribe`
|
||||
- `merge`
|
||||
- `polish`
|
||||
- `normalize`
|
||||
- `trim`
|
||||
- `render`
|
||||
- `extract`
|
||||
- `analyze`
|
||||
- `publish`
|
||||
- `notify`
|
||||
- `cleanup`
|
||||
## Session status
|
||||
|
||||
Rules:
|
||||
|
||||
- `--artifacts` is accepted only for `analyze` and `publish` stage targets.
|
||||
|
||||
### `analyze`
|
||||
|
||||
```bash
|
||||
narratio analyze <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
||||
```sh
|
||||
narratio session status SESSION --format json
|
||||
```
|
||||
|
||||
Equivalent to:
|
||||
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.
|
||||
|
||||
```bash
|
||||
narratio run-stage analyze <session_id> --force [...common config flags]
|
||||
## Session artifacts
|
||||
|
||||
```sh
|
||||
narratio session artifacts SESSION --remote
|
||||
```
|
||||
|
||||
This selects only `analyze`: it does not invoke Notarius, replace extraction,
|
||||
or remove existing extract outputs. `--artifacts` narrows the forced analysis
|
||||
targets and their required analysis prerequisites.
|
||||
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`.
|
||||
|
||||
### `publish`
|
||||
## Session init
|
||||
|
||||
```bash
|
||||
narratio publish <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
||||
```sh
|
||||
narratio session init SESSION --output ./session.yml --audio-dir ./audio
|
||||
narratio session init SESSION --remote --audio-s3-prefix audio/session/
|
||||
```
|
||||
|
||||
Equivalent to:
|
||||
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`.
|
||||
|
||||
```bash
|
||||
narratio run-stage publish <session_id> --force [...common config flags]
|
||||
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
|
||||
```
|
||||
|
||||
This command selects only `publish`; it does not invoke cleanup. Use a normal
|
||||
full run to include configured cleanup, or `run-stage cleanup` to retry cleanup
|
||||
from valid publication evidence.
|
||||
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).
|
||||
|
||||
### `clean`
|
||||
## Session clean
|
||||
|
||||
```bash
|
||||
narratio clean <session_id> [--dry-run] [--clear-cache] [...common config flags]
|
||||
narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]
|
||||
```sh
|
||||
narratio session clean SESSION --dry-run
|
||||
narratio session clean --all --dry-run --clear-cache
|
||||
```
|
||||
|
||||
Behavior:
|
||||
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 mode removes the selected session's local work and spool state;
|
||||
- `--all` removes all local session work and spool state;
|
||||
- cache remains unless `--clear-cache` is provided.
|
||||
## Session locks
|
||||
|
||||
See [Operations: Cleanup](./operations.md#cleanup) for manual and pipeline-stage
|
||||
deletion scope.
|
||||
|
||||
### `session plan`
|
||||
|
||||
```bash
|
||||
narratio session plan <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
|
||||
```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
|
||||
```
|
||||
|
||||
Uses the same inclusive bounds, endpoint validation, force scope, and artifact
|
||||
selection contract as `run`. It validates config and prints run/skip decisions
|
||||
for selected stages only without creating the local workdir or changing the
|
||||
manifest. Resume-capable selected stages are checked against durable evidence.
|
||||
The output includes the resolved overlay (or `none`) and effective configuration
|
||||
digest without writing provenance or any manifest state.
|
||||
For `analyze`, the preview also lists explicit targets, prerequisite-only work,
|
||||
execution order, and reusable current artifacts with concise reasons. These
|
||||
artifact decisions come from the same reconciliation and work planner used by
|
||||
execution; the preview does not predict output identities.
|
||||
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.
|
||||
|
||||
### `session validate`
|
||||
## `--artifacts` selection rules
|
||||
|
||||
```bash
|
||||
narratio session validate <session_id> [...common config flags]
|
||||
`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
|
||||
```
|
||||
|
||||
Read-only preflight checks for config validity, required inputs, audio mode,
|
||||
previous-session requirements, publish outputs, and independent remote locks.
|
||||
- `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.
|
||||
|
||||
### `session status`
|
||||
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).
|
||||
|
||||
```bash
|
||||
narratio session status <session_id> [...common config flags]
|
||||
### 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'
|
||||
```
|
||||
|
||||
Prints local manifest state and, when storage is available, status for the
|
||||
pointer-selected remote commit and its declared published outputs. Current
|
||||
publish metadata reports `published`, `carried_locked`, `locked_unpublished`,
|
||||
`optional_missing`, and `unselected`; carried output lines include the run
|
||||
derived from their exact declared key, the key itself, and its declared
|
||||
destination. A separately displayed `dest` is the destination requested by the
|
||||
current configuration and may differ while an older declaration is locked.
|
||||
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.
|
||||
|
||||
### `session init`
|
||||
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.
|
||||
|
||||
```bash
|
||||
narratio session init <session_id> --output ./session.yml [options]
|
||||
narratio session init <session_id> --remote [options]
|
||||
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
|
||||
```
|
||||
|
||||
Required target selection:
|
||||
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.
|
||||
|
||||
- exactly one of:
|
||||
- `--output <path>`
|
||||
- `--remote`
|
||||
## Migration from the previous CLI
|
||||
|
||||
Options:
|
||||
Removed command paths have no compatibility aliases.
|
||||
|
||||
- `--config <pipeline.yml>`
|
||||
- `--campaign <id>` or `--campaign-file <campaign.yml>`
|
||||
- `--secrets-dir <directory>`
|
||||
- `--previous-session-id <id>`
|
||||
- `--date <YYYY-MM-DD>`
|
||||
- `--title <text>`
|
||||
- `--audio-dir <path>`
|
||||
- `--audio-s3-prefix <prefix>`
|
||||
- `--force`
|
||||
| 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` |
|
||||
|
||||
Rules:
|
||||
|
||||
- `--audio-dir` and `--audio-s3-prefix` are mutually exclusive.
|
||||
- if campaign `session_template_file` is configured, `session init` renders it.
|
||||
- generated session YAML must be concrete (no unresolved `{{ ... }}` placeholders).
|
||||
- template imports and relative resources resolve in the template's local
|
||||
authoring context. Generated output contains standalone effective values.
|
||||
- relative `--audio-dir` paths resolve from the invocation directory.
|
||||
|
||||
### `session restore`
|
||||
|
||||
```bash
|
||||
narratio session restore <session_id> [--dry-run] [--force] [--include-audio] [...common config flags]
|
||||
```
|
||||
|
||||
Behavior:
|
||||
|
||||
- discovers committed remote current state;
|
||||
- plans local restores;
|
||||
- writes an execution report;
|
||||
- blocks unresolved conflicts. `--force` permits replacement only of eligible
|
||||
regular files.
|
||||
|
||||
See [Operations: Restore Workflow](./operations.md#restore-workflow) for the
|
||||
default restore scope, report location, and conflict-handling workflow.
|
||||
|
||||
### `session artifacts`
|
||||
|
||||
```bash
|
||||
narratio session artifacts <session_id> [--remote] [...common config flags]
|
||||
```
|
||||
|
||||
Lists effective built-in, configured Scriptorium, and configured extraction
|
||||
sources; reports planned, available, unavailable, and published state without
|
||||
reading payload bodies; and includes publish rules, lock state, and optional
|
||||
remote published-state availability. Remote inspection uses exact commit
|
||||
declarations and displays the five current publish outcomes when recorded.
|
||||
|
||||
### `session locks`
|
||||
|
||||
```bash
|
||||
narratio session locks <session_id> [...common config flags]
|
||||
narratio session locks add <session_id> <source> [--reason <text>] [--force] [...common config flags]
|
||||
narratio session locks remove <session_id> <source> [...common config flags]
|
||||
```
|
||||
|
||||
Behavior:
|
||||
|
||||
- list mode validates and reports independent remote locks sorted by source;
|
||||
- add creates one lock and reports an existing lock unless `--force` is used;
|
||||
- `--force` performs one generation-matched replacement and reports a
|
||||
concurrent change for operator retry; and
|
||||
- remove is idempotent and reports when the source was not locked.
|
||||
|
||||
See [Operations: Publish Locks](./operations.md#publish-locks) for lock storage
|
||||
and publication behavior.
|
||||
|
||||
## `--artifacts` Selection Rules
|
||||
|
||||
An artifact-family key selects all of its concrete character members. A
|
||||
concrete generated key selects only that member; mixed family and concrete
|
||||
selection is deduplicated and executed as concrete keys. The resulting plan
|
||||
and command output identify both the concrete key and, where applicable, its
|
||||
family and character ID.
|
||||
|
||||
- accepted on `run`, `session plan`, `run-stage`, `analyze`, and `publish`;
|
||||
- repeatable and comma-separated values are combined, surrounding whitespace
|
||||
is removed, and duplicate names are collapsed;
|
||||
- names must exist in `pipeline.scriptorium.artifacts`;
|
||||
- empty entries are invalid;
|
||||
- on `run-stage`, only `analyze` and `publish` accept the option.
|
||||
|
||||
Effects:
|
||||
|
||||
- selects explicit analyze targets; required configured prerequisites may be
|
||||
reused or rebuilt before them;
|
||||
- filters publish rules that source `narratio.artifact.<name>`;
|
||||
- does not filter built-in transcript/bounds or explicitly configured
|
||||
`narratio.extraction.<name>` publish sources; and
|
||||
- does not select or filter Notarius lanes.
|
||||
|
||||
## Common Workflows
|
||||
|
||||
Run full pipeline:
|
||||
|
||||
```bash
|
||||
narratio run 2026-04-04
|
||||
```
|
||||
|
||||
Dry-run restore plan:
|
||||
|
||||
```bash
|
||||
narratio session restore 2026-04-04 --dry-run
|
||||
```
|
||||
|
||||
Generate a concrete session file from template/default structure:
|
||||
|
||||
```bash
|
||||
narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"
|
||||
```
|
||||
|
||||
Force publish only:
|
||||
|
||||
```bash
|
||||
narratio publish 2026-04-04
|
||||
```
|
||||
|
||||
Regenerate post-transcript artifacts without publishing:
|
||||
|
||||
```bash
|
||||
narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout
|
||||
```
|
||||
|
||||
## Output And Exit Behavior
|
||||
|
||||
- Successful commands write their result or summary to standard output and
|
||||
exit with status `0`.
|
||||
- Command failures and invalid invocations write an error to standard error and
|
||||
exit with status `1`.
|
||||
- An unknown top-level command also prints the top-level usage summary to
|
||||
standard error.
|
||||
- `session restore --help` prints its command-specific usage and exits with
|
||||
status `0`.
|
||||
|
||||
Output is intended for operator inspection. Narratio does not currently offer
|
||||
a machine-readable CLI output mode; durable machine-readable state is recorded
|
||||
in manifests and reports described in [Operations](./operations.md).
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user