304 lines
8.0 KiB
Markdown
304 lines
8.0 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:
|
|
|
|
- `run <session_id>`: run full stage order.
|
|
- `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>`
|
|
|
|
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.
|
|
- `clean --all` cannot be combined with campaign/session selectors.
|
|
|
|
## 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
|
|
|
|
### `run`
|
|
|
|
```bash
|
|
narratio run <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
|
|
```
|
|
|
|
Behavior:
|
|
|
|
- evaluates full stage order;
|
|
- runs `extract` between `trim` and `render`; 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;
|
|
- continues interrupted or partially completed sessions by running non-succeeded stages;
|
|
- writes session and run manifests.
|
|
|
|
### `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`
|
|
- `extract`
|
|
- `render`
|
|
- `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> [--force] [...common config flags]
|
|
```
|
|
|
|
Validates config, prepares local workdir layout, and prints run/skip decisions for each stage.
|
|
|
|
### `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`, `run-stage`, `analyze`, and `publish`;
|
|
- names must exist in `pipeline.scriptorium.artifacts`;
|
|
- empty entries are invalid;
|
|
- repeated names are deduplicated.
|
|
|
|
Effects:
|
|
|
|
- filters analyze execution to selected configured artifacts;
|
|
- 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
|
|
```
|
|
|
|
## 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).
|