Rewrite user and operator documentation for current CLI and config behavior
This commit is contained in:
180
docs/cli.md
180
docs/cli.md
@@ -1,4 +1,4 @@
|
||||
# CLI
|
||||
# CLI Reference
|
||||
|
||||
## Shortest Useful Command
|
||||
|
||||
@@ -6,18 +6,19 @@
|
||||
narratio run 2026-04-04
|
||||
```
|
||||
|
||||
This runs the full pipeline for the given session ID using default config discovery and campaign selection.
|
||||
This runs the canonical full pipeline for session `2026-04-04`.
|
||||
|
||||
## Command Overview
|
||||
|
||||
Top-level commands:
|
||||
|
||||
- `run <session_id>`: execute the pipeline.
|
||||
- `run <session_id>`: run full stage order.
|
||||
- `resume <session_id>`: continue from first non-succeeded stage.
|
||||
- `run-stage <stage> <session_id>`: execute exactly one stage.
|
||||
- `analyze <session_id>`: force-rerun analyze stage.
|
||||
- `publish <session_id>`: force-rerun publish stage.
|
||||
- `clean <session_id>|--all`: remove local workspace/spool state.
|
||||
- `session <subcommand>`: session-scoped helper commands.
|
||||
- `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:
|
||||
|
||||
@@ -31,7 +32,8 @@ Session subcommands:
|
||||
- `session locks add <session_id> <source>`
|
||||
- `session locks remove <session_id> <source>`
|
||||
|
||||
## Common Flags
|
||||
## Common Config Flags
|
||||
|
||||
Most session-aware commands accept:
|
||||
|
||||
- `--config <pipeline.yml>`
|
||||
@@ -40,30 +42,41 @@ Most session-aware commands accept:
|
||||
- `--session <session.yml>`
|
||||
- `--previous-session-id <id>`
|
||||
|
||||
`--campaign` and `--campaign-file` are mutually exclusive.
|
||||
Rules:
|
||||
|
||||
- `--campaign` and `--campaign-file` are mutually exclusive.
|
||||
- `--session` is not used by `session init`.
|
||||
- `clean --all` cannot be combined with campaign/session selectors.
|
||||
|
||||
## Command Reference
|
||||
|
||||
### `run`
|
||||
|
||||
```bash
|
||||
narratio run <session_id> [--force] [--artifacts <name[,name...]>] [...common flags]
|
||||
narratio run <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
|
||||
```
|
||||
|
||||
Runs stages in canonical order and writes manifest state.
|
||||
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 flags]
|
||||
narratio resume <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
|
||||
```
|
||||
|
||||
Starts at the first non-succeeded stage from the session manifest.
|
||||
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 flags]
|
||||
narratio run-stage <stage> <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
|
||||
```
|
||||
|
||||
Valid stage names:
|
||||
@@ -78,123 +91,161 @@ Valid stage names:
|
||||
- `publish`
|
||||
- `notify`
|
||||
|
||||
`--artifacts` is accepted only for `analyze` and `publish`.
|
||||
Rules:
|
||||
|
||||
- `--artifacts` is accepted only for `analyze` and `publish` stage targets.
|
||||
|
||||
### `analyze`
|
||||
|
||||
```bash
|
||||
narratio analyze <session_id> [--artifacts <name[,name...]>] [...common flags]
|
||||
narratio analyze <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
||||
```
|
||||
|
||||
Equivalent to `narratio run-stage analyze <session_id> --force`.
|
||||
Equivalent to:
|
||||
|
||||
```bash
|
||||
narratio run-stage analyze <session_id> --force [...common config flags]
|
||||
```
|
||||
|
||||
### `publish`
|
||||
|
||||
```bash
|
||||
narratio publish <session_id> [--artifacts <name[,name...]>] [...common flags]
|
||||
narratio publish <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
||||
```
|
||||
|
||||
Equivalent to `narratio run-stage publish <session_id> --force`.
|
||||
Equivalent to:
|
||||
|
||||
```bash
|
||||
narratio run-stage publish <session_id> --force [...common config flags]
|
||||
```
|
||||
|
||||
### `clean`
|
||||
|
||||
```bash
|
||||
narratio clean <session_id> [--dry-run] [--clear-cache] [...common flags]
|
||||
narratio clean <session_id> [--dry-run] [--clear-cache] [...common config flags]
|
||||
narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]
|
||||
```
|
||||
|
||||
- session mode deletes `{workspace.root}/work/{campaign}/{session_id}` and `{spool.root}/{campaign}/{session_id}`.
|
||||
- `--all` deletes all session work and spool children.
|
||||
- cache is preserved unless `--clear-cache` is passed.
|
||||
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 flags]
|
||||
narratio session plan <session_id> [--force] [...common config flags]
|
||||
```
|
||||
|
||||
Validates config and session inputs, prepares workdir layout, and prints stage run/skip decisions.
|
||||
Validates config, prepares local workdir layout, and prints run/skip decisions for each stage.
|
||||
|
||||
### `session validate`
|
||||
|
||||
```bash
|
||||
narratio session validate <session_id> [...common flags]
|
||||
narratio session validate <session_id> [...common config flags]
|
||||
```
|
||||
|
||||
Read-only preflight checks for config, inputs, audio availability, previous-session requirements, publish outputs, and effective locks.
|
||||
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 flags]
|
||||
narratio session status <session_id> [...common config flags]
|
||||
```
|
||||
|
||||
Shows local manifest state, remote current state (when storage is configured), published-output availability, and effective locks.
|
||||
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
|
||||
narratio session init <session_id> --remote
|
||||
narratio session init <session_id> --remote --force
|
||||
narratio session init <session_id> --output ./session.yml [options]
|
||||
narratio session init <session_id> --remote [options]
|
||||
```
|
||||
|
||||
Flags:
|
||||
Required target selection:
|
||||
|
||||
- `--output <path>` or `--remote` (exactly one is required)
|
||||
- exactly one of:
|
||||
- `--output <path>`
|
||||
- `--remote`
|
||||
|
||||
Options:
|
||||
|
||||
- `--config <pipeline.yml>`
|
||||
- `--campaign <id>` or `--campaign-file <campaign.yml>`
|
||||
- `--previous-session-id <id>`
|
||||
- `--date <date>`
|
||||
- `--title <title>`
|
||||
- `--date <YYYY-MM-DD>`
|
||||
- `--title <text>`
|
||||
- `--audio-dir <path>`
|
||||
- `--audio-s3-prefix <prefix>`
|
||||
- `--force`
|
||||
- common config/campaign flags
|
||||
|
||||
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 flags]
|
||||
narratio session restore <session_id> [--dry-run] [--force] [--include-audio] [...common config flags]
|
||||
```
|
||||
|
||||
Restores durable local session files from committed remote current state.
|
||||
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 artifact inputs
|
||||
- `previous/**` when required by configured previous-session inputs
|
||||
|
||||
`audio/**` is restored only when `--include-audio` is set.
|
||||
`audio/**` is included only with `--include-audio`.
|
||||
|
||||
### `session artifacts`
|
||||
|
||||
```bash
|
||||
narratio session artifacts <session_id> [--remote] [...common flags]
|
||||
narratio session artifacts <session_id> [--remote] [...common config flags]
|
||||
```
|
||||
|
||||
Lists built-in sources, configured artifact sources, previous-session sources, publish output rules, and lock status. With `--remote`, includes remote published-state markers.
|
||||
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 flags]
|
||||
narratio session locks add <session_id> <source> [--reason <text>] [--force] [...common flags]
|
||||
narratio session locks remove <session_id> <source> [...common flags]
|
||||
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]
|
||||
```
|
||||
|
||||
- list mode prints effective locks from static `pipeline.publish.locks` and remote `{session_prefix}/locks.yml`.
|
||||
- add/remove mutate only the remote lock store.
|
||||
- static pipeline locks cannot be removed by lock commands.
|
||||
Behavior:
|
||||
|
||||
## `--artifacts` Rules
|
||||
- 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.
|
||||
|
||||
- accepted on `run`, `resume`, `run-stage`, `analyze`, and `publish`.
|
||||
- on `run-stage`, only valid for `analyze` and `publish`.
|
||||
- filters configured analyze artifact execution.
|
||||
- filters configured `pipeline.publish.outputs` entries for `narratio.artifact.<key>` sources.
|
||||
- does not suppress built-in transcript/bounds publish outputs.
|
||||
- does not imply `--force` for `run`, `resume`, or `run-stage`.
|
||||
## `--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
|
||||
|
||||
@@ -204,16 +255,16 @@ Run full pipeline:
|
||||
narratio run 2026-04-04
|
||||
```
|
||||
|
||||
Run only selected analyze artifacts:
|
||||
Dry-run restore plan:
|
||||
|
||||
```bash
|
||||
narratio run 2026-04-04 --artifacts session_recap,player_handout
|
||||
narratio session restore 2026-04-04 --dry-run
|
||||
```
|
||||
|
||||
Force analyze only:
|
||||
Generate a concrete session file from template/default structure:
|
||||
|
||||
```bash
|
||||
narratio analyze 2026-04-04 --artifacts player_handout
|
||||
narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"
|
||||
```
|
||||
|
||||
Force publish only:
|
||||
@@ -221,10 +272,3 @@ Force publish only:
|
||||
```bash
|
||||
narratio publish 2026-04-04
|
||||
```
|
||||
|
||||
Restore preview then apply:
|
||||
|
||||
```bash
|
||||
narratio session restore 2026-04-04 --dry-run
|
||||
narratio session restore 2026-04-04
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user