292 lines
7.1 KiB
Markdown
292 lines
7.1 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.
|
|
- `resume <session_id>`: continue from first non-succeeded stage.
|
|
- `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;
|
|
- skips already-succeeded stages unless `--force` is set;
|
|
- writes session and run manifests.
|
|
|
|
### `resume`
|
|
|
|
```bash
|
|
narratio resume <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
|
|
```
|
|
|
|
Behavior:
|
|
|
|
- when not forced, starts at first non-succeeded stage in manifest order;
|
|
- with `--force`, reevaluates the selected stage list as runnable.
|
|
|
|
### `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`
|
|
- `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:
|
|
- `{workspace.root}/work/{campaign}/{session_id}`
|
|
- `{spool.root}/{campaign}/{session_id}`
|
|
- `--all` removes:
|
|
- `{workspace.root}/work/*`
|
|
- direct children under `{spool.root}`
|
|
- cache remains unless `--clear-cache` is provided.
|
|
|
|
### `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, remote current-state and published-output status.
|
|
|
|
### `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 `reports/restore-latest.json` on execution;
|
|
- blocks conflicting overwrites unless `--force` is set.
|
|
|
|
Default restore scope:
|
|
|
|
- `manifest.json`
|
|
- `transcripts/**`
|
|
- `artifacts/**`
|
|
- `previous/**` when required by configured previous-session inputs
|
|
|
|
`audio/**` is included only with `--include-audio`.
|
|
|
|
### `session artifacts`
|
|
|
|
```bash
|
|
narratio session artifacts <session_id> [--remote] [...common config flags]
|
|
```
|
|
|
|
Lists effective built-in and configured artifact sources, 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 merges static `pipeline.publish.locks` with remote `{session_prefix}/locks.yml`;
|
|
- add/remove mutate only remote locks;
|
|
- static locks from pipeline config cannot be removed by CLI commands.
|
|
|
|
## `--artifacts` Selection Rules
|
|
|
|
- accepted on `run`, `resume`, `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 publish sources.
|
|
|
|
## 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
|
|
```
|