375 lines
12 KiB
Markdown
375 lines
12 KiB
Markdown
# 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.
|
|
|
|
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>`
|
|
- `--profile <name>`
|
|
|
|
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`.
|
|
- `--profile` selects a declared pipeline profile. It may be supplied once;
|
|
an explicit empty or unknown value fails configuration resolution. When it is
|
|
omitted, a declared `default_profile` is used. The same selection applies to
|
|
all common-flag commands, including `regenerate-artifacts`.
|
|
- `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
|
|
|
|
### `version`
|
|
|
|
```bash
|
|
narratio version
|
|
```
|
|
|
|
Official release binaries report their exact Git tag. Binaries built directly
|
|
from source without release linker metadata report `dev`.
|
|
|
|
### `run`
|
|
|
|
```bash
|
|
narratio run <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
|
|
```
|
|
|
|
Behavior:
|
|
|
|
- evaluates one inclusive contiguous range of the canonical stage order;
|
|
- defaults an omitted `--from` to `prepare` and an omitted `--through` to
|
|
`notify`, 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;
|
|
- 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 session and run manifests.
|
|
- reports the resolved profile (or `none`) and effective configuration digest.
|
|
|
|
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]
|
|
```
|
|
|
|
Exactly equivalent to:
|
|
|
|
```bash
|
|
narratio run <session_id> --force --from extract --through analyze [caller options]
|
|
```
|
|
|
|
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.
|
|
|
|
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]
|
|
```
|
|
|
|
Valid stage names:
|
|
|
|
- `prepare`
|
|
- `transcribe`
|
|
- `merge`
|
|
- `polish`
|
|
- `normalize`
|
|
- `trim`
|
|
- `render`
|
|
- `extract`
|
|
- `analyze`
|
|
- `publish`
|
|
- `notify`
|
|
|
|
Rules:
|
|
|
|
- `--artifacts` is accepted only for `analyze` and `publish` stage targets.
|
|
|
|
### `analyze`
|
|
|
|
```bash
|
|
narratio analyze <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
|
```
|
|
|
|
Equivalent to:
|
|
|
|
```bash
|
|
narratio run-stage analyze <session_id> --force [...common config flags]
|
|
```
|
|
|
|
### `publish`
|
|
|
|
```bash
|
|
narratio publish <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
|
```
|
|
|
|
Equivalent to:
|
|
|
|
```bash
|
|
narratio run-stage publish <session_id> --force [...common config flags]
|
|
```
|
|
|
|
### `clean`
|
|
|
|
```bash
|
|
narratio clean <session_id> [--dry-run] [--clear-cache] [...common config flags]
|
|
narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]
|
|
```
|
|
|
|
Behavior:
|
|
|
|
- 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.
|
|
|
|
See [Operations: Cleanup](./operations.md#cleanup) for deletion scope and
|
|
post-publish cleanup behavior.
|
|
|
|
### `session plan`
|
|
|
|
```bash
|
|
narratio session plan <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
|
|
```
|
|
|
|
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 profile (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.
|
|
|
|
### `session validate`
|
|
|
|
```bash
|
|
narratio session validate <session_id> [...common config flags]
|
|
```
|
|
|
|
Read-only preflight checks for config validity, required inputs, audio mode, previous-session requirements, publish outputs, and effective locks.
|
|
|
|
### `session status`
|
|
|
|
```bash
|
|
narratio session status <session_id> [...common config flags]
|
|
```
|
|
|
|
Prints local manifest state and, when storage is available, status for the
|
|
pointer-selected remote commit and its declared published outputs.
|
|
|
|
### `session init`
|
|
|
|
```bash
|
|
narratio session init <session_id> --output ./session.yml [options]
|
|
narratio session init <session_id> --remote [options]
|
|
```
|
|
|
|
Required target selection:
|
|
|
|
- exactly one of:
|
|
- `--output <path>`
|
|
- `--remote`
|
|
|
|
Options:
|
|
|
|
- `--config <pipeline.yml>`
|
|
- `--campaign <id>` or `--campaign-file <campaign.yml>`
|
|
- `--previous-session-id <id>`
|
|
- `--date <YYYY-MM-DD>`
|
|
- `--title <text>`
|
|
- `--audio-dir <path>`
|
|
- `--audio-s3-prefix <prefix>`
|
|
- `--force`
|
|
|
|
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).
|
|
|
|
### `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.
|
|
|
|
### `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 reports the effective merge of static and remote locks;
|
|
- add/remove mutate only remote locks;
|
|
- static locks from pipeline config cannot be removed by CLI commands.
|
|
|
|
See [Operations: Publish Locks](./operations.md#publish-locks) for lock storage
|
|
and precedence.
|
|
|
|
## `--artifacts` Selection Rules
|
|
|
|
- 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).
|