223 lines
5.4 KiB
Markdown
223 lines
5.4 KiB
Markdown
# CLI
|
|
|
|
## Shortest Useful Command
|
|
|
|
```bash
|
|
narratio run --session-id 2026-04-04
|
|
```
|
|
|
|
This command uses default config discovery for `pipeline.yml` and `session.yml`; both files must be discoverable unless you pass explicit `--config` and `--session` paths.
|
|
|
|
## Command Overview
|
|
|
|
Implemented commands:
|
|
|
|
- `run`: execute pipeline stages and persist manifest state.
|
|
- `plan`: validate config, prepare workspace layout, and print stage run/skip decisions.
|
|
- `resume`: continue from first non-succeeded stage unless forced.
|
|
- `status`: read and print stage statuses from an existing manifest.
|
|
- `run-stage`: execute exactly one stage.
|
|
|
|
Unknown commands print usage and exit non-zero.
|
|
|
|
For config semantics, see [docs/config.md](./config.md). For operator lifecycle and recovery, see [docs/operations.md](./operations.md).
|
|
|
|
## Complete Flag Reference
|
|
|
|
### `run`
|
|
|
|
- `--config <path>`: optional explicit `pipeline.yml` path.
|
|
- `--session <path>`: optional explicit `session.yml` path.
|
|
- `--session-id <value>`: session template variable value.
|
|
- `--force`: force stage execution.
|
|
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
|
|
|
|
### `plan`
|
|
|
|
- `--config <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--force`
|
|
|
|
### `resume`
|
|
|
|
- `--config <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--force`
|
|
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
|
|
|
|
### `run-stage`
|
|
|
|
- `--config <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--force`
|
|
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
|
|
- positional `<stage>`: required stage name.
|
|
|
|
Valid stage names:
|
|
|
|
- `prepare`
|
|
- `transcribe`
|
|
- `merge`
|
|
- `polish`
|
|
- `normalize`
|
|
- `trim`
|
|
- `analyze`
|
|
- `archive`
|
|
- `notify`
|
|
|
|
### `status`
|
|
|
|
- `--manifest <path>`: required manifest path.
|
|
|
|
## Command Reference
|
|
|
|
### `run`
|
|
|
|
Purpose:
|
|
- Execute configured stages in canonical order.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio run [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force] [--artifacts <name[,name...]>]
|
|
```
|
|
|
|
Success output:
|
|
- `narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
|
|
|
|
Common failure cases:
|
|
- missing default config/session paths when flags omitted.
|
|
- invalid template/rendered session mismatch.
|
|
- unknown/invalid `--artifacts` value.
|
|
- `--artifacts` with unknown configured artifact key.
|
|
|
|
### `plan`
|
|
|
|
Purpose:
|
|
- Validate config, load secrets (if configured), prepare workdir, and print stage run/skip decisions.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio plan [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force]
|
|
```
|
|
|
|
Success output includes:
|
|
- `narratio plan: workdir prepared at <path>`
|
|
- one line per stage (`<stage>: run|skip`)
|
|
- `totals: run=<n> skip=<n>`
|
|
|
|
Common failure cases:
|
|
- same config/session discovery and validation failures as `run`.
|
|
- secrets directory read failures when `pipeline.secrets.env_dir` is configured.
|
|
|
|
### `resume`
|
|
|
|
Purpose:
|
|
- Continue from session-manifest stage status.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio resume [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force] [--artifacts <name[,name...]>]
|
|
```
|
|
|
|
Success output:
|
|
- `narratio resume: session <session_id> has no remaining stages`
|
|
- or `narratio resume: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
|
|
|
|
Common failure cases:
|
|
- same discovery/template/validation failures as `run`.
|
|
- manifest load errors when existing manifest is unreadable.
|
|
- invalid or unknown artifact selections.
|
|
|
|
### `status`
|
|
|
|
Purpose:
|
|
- Inspect one manifest file without executing stages.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio status --manifest <manifest.json>
|
|
```
|
|
|
|
Success output includes:
|
|
- `session_id: <id>`
|
|
- `updated_at: <timestamp>`
|
|
- `stages:` entries (`- <stage>: <status>`)
|
|
|
|
Common failure cases:
|
|
- missing `--manifest`.
|
|
- unreadable or invalid manifest path.
|
|
|
|
### `run-stage`
|
|
|
|
Purpose:
|
|
- Execute exactly one stage.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio run-stage [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force] [--artifacts <name[,name...]>] <stage>
|
|
```
|
|
|
|
Success output:
|
|
- `narratio run-stage: stage=<name> executed=<n> skipped=<n> force=<true|false>; manifest=<path>`
|
|
|
|
`--artifacts` behavior:
|
|
- accepted only when `<stage>` is `analyze`.
|
|
- names are normalized (trimmed, deduplicated, sorted).
|
|
- unknown configured artifact keys fail.
|
|
|
|
Common failure cases:
|
|
- missing stage positional arg.
|
|
- unknown stage name.
|
|
- using `--artifacts` with any non-`analyze` stage.
|
|
|
|
## Common Workflows
|
|
|
|
Default-discovery run:
|
|
|
|
```bash
|
|
narratio run --session-id 2026-04-04
|
|
```
|
|
|
|
Run only selected analyze artifacts:
|
|
|
|
```bash
|
|
narratio run --session-id 2026-04-04 --artifacts session_recap,player_handout
|
|
```
|
|
|
|
Resume with selected analyze artifacts:
|
|
|
|
```bash
|
|
narratio resume --session-id 2026-04-04 --artifacts player_handout
|
|
```
|
|
|
|
Run only analyze stage with selected artifacts:
|
|
|
|
```bash
|
|
narratio run-stage --session-id 2026-04-04 --artifacts player_handout analyze
|
|
```
|
|
|
|
## Diagnostic / Recovery Commands
|
|
|
|
Inspect stage status:
|
|
|
|
```bash
|
|
narratio status --manifest <manifest.json>
|
|
```
|
|
|
|
Get manifest path from previous output:
|
|
- `run`, `resume`, and `run-stage` print `manifest=<path>` on success.
|
|
|
|
## `--artifacts` and `--force`
|
|
|
|
- `--artifacts` filters which configured artifacts are executable when analyze runs.
|
|
- `--artifacts` does not imply `--force`.
|
|
- If analyze is already `succeeded` and `--force` is not set, runner-level skip still applies.
|