576 lines
18 KiB
Markdown
576 lines
18 KiB
Markdown
# CLI
|
|
|
|
## Shortest Useful Command
|
|
|
|
```bash
|
|
narratio run --session-id 2026-04-04
|
|
```
|
|
|
|
This command uses default system discovery for `pipeline.yml`, `campaign.yml`, and local `session.yml`. If local session discovery misses and S3 storage is configured, `--session-id` can load remote `session.yml` from the canonical session prefix.
|
|
|
|
Default discovery checks system config locations only. Pass `--config`, `--campaign`, and `--session` to use files from the current working directory.
|
|
|
|
## 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 an existing manifest or inspect local/remote state for a session.
|
|
- `run-stage`: execute exactly one stage.
|
|
- `analyze`: force-rerun the analyze stage.
|
|
- `publish`: force-rerun the archive stage.
|
|
- `restore`: restore durable local session state from the committed remote archive state.
|
|
- `session validate`: run read-only preflight checks for a session.
|
|
- `session init`: create local or remote `session.yml`.
|
|
- `artifacts list`: list effective artifact source IDs.
|
|
- `locks`: list, add, and remove archive promotion locks.
|
|
- `clean`: remove local workspace/spool state for one session or all local sessions.
|
|
|
|
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.
|
|
- `--campaign <path>`: optional explicit `campaign.yml` path.
|
|
- `--session <path>`: optional explicit `session.yml` path.
|
|
- `--session-id <value>`: session template variable value.
|
|
- `--previous-session-id <value>`: previous-session template variable value.
|
|
- `--force`: force stage execution.
|
|
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
|
|
|
|
### `plan`
|
|
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--previous-session-id <value>`
|
|
- `--force`
|
|
|
|
### `resume`
|
|
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--previous-session-id <value>`
|
|
- `--force`
|
|
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
|
|
|
|
### `run-stage`
|
|
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--previous-session-id <value>`
|
|
- `--force`
|
|
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
|
|
- positional `<stage>`: required stage name.
|
|
|
|
### `analyze`
|
|
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--previous-session-id <value>`
|
|
- `--artifacts <names>`: analyze artifact keys to execute (repeatable or comma-separated).
|
|
|
|
`analyze` is force-by-design and does not accept `--force`.
|
|
|
|
### `publish`
|
|
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--previous-session-id <value>`
|
|
|
|
`publish` is force-by-design and does not accept `--force`, `--artifacts`, or a stage positional argument.
|
|
|
|
Valid stage names:
|
|
|
|
- `prepare`
|
|
- `transcribe`
|
|
- `merge`
|
|
- `polish`
|
|
- `normalize`
|
|
- `trim`
|
|
- `analyze`
|
|
- `archive`
|
|
- `notify`
|
|
|
|
### `restore`
|
|
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--previous-session-id <value>`
|
|
- `--dry-run`: plan restore actions without writing local files.
|
|
- `--force`: overwrite local conflicting files with remote archive files.
|
|
- `--include-audio`: include durable archived `audio/**` files in restore scope.
|
|
|
|
### `clean`
|
|
|
|
- `--session-id <value>`: required for session cleanup unless `--all` is set.
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--previous-session-id <value>`
|
|
- `--all`: clean all local session work/spool state using pipeline config only.
|
|
- `--dry-run`: print cleanup targets without deleting.
|
|
- `--clear-cache`: also remove matching S3 audio cache entries.
|
|
|
|
### `status`
|
|
|
|
- `--manifest <path>`: inspect one manifest file.
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--previous-session-id <value>`
|
|
|
|
### `session validate`
|
|
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--previous-session-id <value>`
|
|
|
|
### `session init`
|
|
|
|
- `--config <path>`: required.
|
|
- `--campaign <path>`: required.
|
|
- `--session-id <value>`: required.
|
|
- `--output <path>`: local `session.yml` target; mutually exclusive with `--remote`.
|
|
- `--remote`: write remote `session.yml` to the canonical session prefix; mutually exclusive with `--output`.
|
|
- `--previous-session-id <value>`
|
|
- `--date <value>`
|
|
- `--title <value>`
|
|
- `--audio-s3-prefix <prefix>`: defaults to `audio/` when neither audio flag is provided.
|
|
- `--audio-dir <path>`: local audio directory; mutually exclusive with `--audio-s3-prefix`.
|
|
- `--force`: overwrite existing local or remote target.
|
|
|
|
### `artifacts list`
|
|
|
|
- `--config <path>`
|
|
- `--campaign <path>`
|
|
- `--session <path>`
|
|
- `--session-id <value>`
|
|
- `--previous-session-id <value>`
|
|
- `--remote`: check remote availability for configured archive promotion destinations.
|
|
|
|
### `locks`
|
|
|
|
- `--session-id <value>`: required for list, add, and remove.
|
|
- `--config <path>`: optional explicit `pipeline.yml` path.
|
|
- `--campaign <path>`: optional explicit `campaign.yml` path.
|
|
- `--session <path>`: optional explicit `session.yml` path.
|
|
- `--previous-session-id <value>`: optional session template value.
|
|
- `add <source>`: add a remote lock for one artifact or transcript source.
|
|
- `add --reason <text>`: record an optional remote lock reason.
|
|
- `add --force`: update the reason for an existing remote lock.
|
|
- `remove <source>`: remove one remote lock.
|
|
|
|
## Command Reference
|
|
|
|
### `run`
|
|
|
|
Purpose:
|
|
- Execute configured stages in canonical order.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio run [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>]
|
|
```
|
|
|
|
Success output:
|
|
- `narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
|
|
|
|
Common failure cases:
|
|
- missing system default config/campaign/session paths when flags omitted.
|
|
- missing local session plus missing/unavailable remote `session.yml`.
|
|
- 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>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-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/campaign/session discovery and validation failures as `run`.
|
|
- remote session fallback failures when local session discovery misses.
|
|
- 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>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-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, or inspect configured local/remote state for a session.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio status --manifest <manifest.json>
|
|
narratio status [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>]
|
|
```
|
|
|
|
Manifest output includes:
|
|
- `session_id: <id>`
|
|
- `updated_at: <timestamp>`
|
|
- `stages:` entries (`- <stage>: <status>`)
|
|
|
|
Session output includes:
|
|
- session ID, campaign, workspace, session config source.
|
|
- local manifest state when present.
|
|
- remote current archive state when storage is configured.
|
|
- catalog-based remote output availability for expected transcript and artifact sources.
|
|
- effective archive locks and conservative next actions.
|
|
|
|
Common failure cases:
|
|
- missing `--manifest` when no config/session flags are provided.
|
|
- unreadable or invalid manifest path.
|
|
- invalid config or remote session fallback failure in session mode.
|
|
|
|
### `session validate`
|
|
|
|
Purpose:
|
|
- Run read-only preflight checks for a session.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio session validate [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>]
|
|
```
|
|
|
|
Checks include:
|
|
- effective config and session source.
|
|
- stable input files.
|
|
- local or remote audio availability.
|
|
- previous-session requirements.
|
|
- archive promotions and effective locks.
|
|
|
|
Warnings do not fail the command. Any `ERROR` finding exits non-zero.
|
|
|
|
### `session init`
|
|
|
|
Purpose:
|
|
- Create a strict-decoded session skeleton locally or in object storage.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio session init --config <pipeline.yml> --campaign <campaign.yml> --session-id <id> --output ./session.yml
|
|
narratio session init --config <pipeline.yml> --campaign <campaign.yml> --session-id <id> --remote
|
|
```
|
|
|
|
Behavior:
|
|
- exactly one of `--output` or `--remote` is required.
|
|
- remote writes target `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`.
|
|
- existing local or remote targets fail unless `--force` is passed.
|
|
- remote writes use existence checks, not compare-and-swap.
|
|
|
|
### `artifacts list`
|
|
|
|
Purpose:
|
|
- List built-in, configured, previous-session, promoted, and locked artifact sources.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio artifacts list [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--remote]
|
|
```
|
|
|
|
`--remote` checks promoted top-level object availability through the storage adapter. Remote markers appear only in the `Promoted` section, which reports each configured archive promotion destination and includes `dest=<path>` when that destination differs from the source's canonical path.
|
|
|
|
### `locks`
|
|
|
|
Purpose:
|
|
- Inspect and mutate source-based archive promotion locks for one session.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio locks --session-id <id>
|
|
narratio locks add --session-id <id> [--reason <text>] [--force] <source>
|
|
narratio locks remove --session-id <id> <source>
|
|
```
|
|
|
|
Behavior:
|
|
- `--session-id` is required for list, add, and remove.
|
|
- optional `--config`, `--campaign`, and `--session` override default config discovery.
|
|
- list mode prints effective locks from static `pipeline.archive.locks` and remote `{session_prefix}/locks.yml`.
|
|
- `locks add` writes only the remote lock store and fails if the source is already locked by pipeline config.
|
|
- `locks remove` removes only remote locks and cannot remove static pipeline locks.
|
|
- `locks add --force` is required to update an existing remote lock reason.
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
narratio locks --session-id 2026-04-04
|
|
narratio locks add --session-id 2026-04-04 --reason "manual transcript review" narratio.transcript.trimmed
|
|
narratio locks remove --session-id 2026-04-04 narratio.transcript.trimmed
|
|
```
|
|
|
|
### `run-stage`
|
|
|
|
Purpose:
|
|
- Execute exactly one stage.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio run-stage [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-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.
|
|
|
|
### `analyze`
|
|
|
|
Purpose:
|
|
- Force-rerun the analyze stage.
|
|
- Provide a shorter equivalent for `narratio run-stage --force analyze`.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio analyze [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--artifacts <name[,name...]>]
|
|
```
|
|
|
|
Success output:
|
|
- `narratio analyze: executed=<n> skipped=<n> force=true; manifest=<path>`
|
|
|
|
Common failure cases:
|
|
- positional arguments.
|
|
- `--force`, because force is implicit.
|
|
- unknown configured artifact keys.
|
|
|
|
### `publish`
|
|
|
|
Purpose:
|
|
- Force-rerun the archive stage.
|
|
- Provide a shorter equivalent for `narratio run-stage --force archive`.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio publish [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>]
|
|
```
|
|
|
|
Success output:
|
|
- `narratio publish: executed=<n> skipped=<n> force=true; manifest=<path>`
|
|
|
|
Common failure cases:
|
|
- positional arguments.
|
|
- `--force`, because force is implicit.
|
|
- `--artifacts`, because artifact selection only applies to analyze.
|
|
- archive-stage failures such as missing required promotion sources or locked storage errors.
|
|
|
|
### `restore`
|
|
|
|
Purpose:
|
|
- Restore durable session state from the committed remote archive current state.
|
|
- Default restore installs `manifest.json`, `transcripts/**`, and `artifacts/**` from the current session archive.
|
|
- When configured previous-session inputs require it, restore reconstructs `previous/**` from the previous session's committed current archive, matching what `prepare` would hydrate.
|
|
- `audio/**` is restored only with `--include-audio`.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio restore [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>] [--dry-run] [--force] [--include-audio]
|
|
```
|
|
|
|
Success output (dry-run):
|
|
- `Restore plan for <campaign>/<session_id>`
|
|
- `Remote run: <run_id>`
|
|
- `Would download: <n>`
|
|
- `Would skip unchanged: <n>`
|
|
- `Conflicts: <n>`
|
|
|
|
Success output (non-dry-run):
|
|
- `Restored session archive for <campaign>/<session_id>`
|
|
- `Remote run: <run_id>`
|
|
- `Downloaded: <n>`
|
|
- `Skipped unchanged: <n>`
|
|
- `Conflicts: <n>`
|
|
|
|
Common failure cases:
|
|
- storage backend is not configured.
|
|
- remote `current/run_id.txt` missing/empty.
|
|
- remote `current/manifest.json` missing or invalid.
|
|
- remote manifest session/campaign mismatch.
|
|
- required previous-session current state or artifact missing.
|
|
- local conflicts without `--force`.
|
|
- session lock conflict.
|
|
|
|
Dry-run output may include planned previous-cache downloads. Existing differing files under `previous/**` follow the normal restore conflict policy and require `--force` to overwrite.
|
|
|
|
When `--include-audio` is set, S3 audio files are restored through the shared audio cache. Cache hits avoid re-downloading large audio objects.
|
|
|
|
### `clean`
|
|
|
|
Purpose:
|
|
- Remove local Narratio work/spool state for testing, reruns, or recovery from corrupted local files.
|
|
- Preserve durable S3 audio cache state unless `--clear-cache` is passed.
|
|
|
|
Syntax:
|
|
|
|
```bash
|
|
narratio clean --session-id <id> [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--dry-run] [--clear-cache]
|
|
narratio clean --all [--config <pipeline.yml>] [--dry-run] [--clear-cache]
|
|
```
|
|
|
|
Session cleanup deletes:
|
|
- `{workspace.root}/work/{campaign}/{session_id}`
|
|
- `{spool.root}/{campaign}/{session_id}`
|
|
|
|
All-session cleanup deletes:
|
|
- `{workspace.root}/work`
|
|
- the contents of `{spool.root}`, while preserving the spool root directory itself.
|
|
|
|
Cache behavior:
|
|
- cache is preserved by default.
|
|
- `--clear-cache` in session mode removes cached S3 audio files for the resolved session.
|
|
- `--all --clear-cache` removes the configured Narratio S3 audio cache namespace for the configured bucket/root prefix.
|
|
- `--clear-cache` does not delete arbitrary files under `pipeline.cache.root`.
|
|
|
|
Common failure cases:
|
|
- missing `--session-id` when `--all` is not set.
|
|
- combining `--all` with `--campaign`, `--session`, `--session-id`, or `--previous-session-id`.
|
|
- unsafe cleanup target, such as a symlink, a non-directory session target, a configured root directory, or a path outside the configured root.
|
|
|
|
## 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
|
|
```
|
|
|
|
Force-rerun analyze with selected artifacts:
|
|
|
|
```bash
|
|
narratio analyze --session-id 2026-04-04 --artifacts player_handout
|
|
```
|
|
|
|
Force-rerun archive publishing:
|
|
|
|
```bash
|
|
narratio publish --session-id 2026-04-04
|
|
```
|
|
|
|
Preview restore actions without writes:
|
|
|
|
```bash
|
|
narratio restore --session-id 2026-04-04 --dry-run
|
|
```
|
|
|
|
Restore and then force analyze:
|
|
|
|
```bash
|
|
narratio restore --session-id 2026-04-04
|
|
narratio analyze --session-id 2026-04-04
|
|
```
|
|
|
|
Rehydrate canonical previous-session inputs after artifact-input changes:
|
|
|
|
```bash
|
|
narratio run-stage --session-id 2026-04-04 --force prepare
|
|
```
|
|
|
|
Reset local state before testing restore:
|
|
|
|
```bash
|
|
narratio clean --session-id 2026-04-04 --dry-run
|
|
narratio clean --session-id 2026-04-04
|
|
narratio restore --session-id 2026-04-04 --include-audio
|
|
```
|
|
|
|
Clean all local sessions while keeping cached S3 audio:
|
|
|
|
```bash
|
|
narratio clean --all
|
|
```
|
|
|
|
## Diagnostic / Recovery Commands
|
|
|
|
Inspect stage status:
|
|
|
|
```bash
|
|
narratio status --manifest <manifest.json>
|
|
```
|
|
|
|
Get manifest path from previous output:
|
|
- `run`, `resume`, `run-stage`, `analyze`, and `publish` 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.
|