# 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 `: optional explicit `pipeline.yml` path. - `--campaign `: optional explicit `campaign.yml` path. - `--session `: optional explicit `session.yml` path. - `--session-id `: session template variable value. - `--previous-session-id `: previous-session template variable value. - `--force`: force stage execution. - `--artifacts `: analyze artifact keys to execute (repeatable or comma-separated). ### `plan` - `--config ` - `--campaign ` - `--session ` - `--session-id ` - `--previous-session-id ` - `--force` ### `resume` - `--config ` - `--campaign ` - `--session ` - `--session-id ` - `--previous-session-id ` - `--force` - `--artifacts `: analyze artifact keys to execute (repeatable or comma-separated). ### `run-stage` - `--config ` - `--campaign ` - `--session ` - `--session-id ` - `--previous-session-id ` - `--force` - `--artifacts `: analyze artifact keys to execute (repeatable or comma-separated). - positional ``: required stage name. ### `analyze` - `--config ` - `--campaign ` - `--session ` - `--session-id ` - `--previous-session-id ` - `--artifacts `: analyze artifact keys to execute (repeatable or comma-separated). `analyze` is force-by-design and does not accept `--force`. ### `publish` - `--config ` - `--campaign ` - `--session ` - `--session-id ` - `--previous-session-id ` `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 ` - `--campaign ` - `--session ` - `--session-id ` - `--previous-session-id ` - `--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 `: required for session cleanup unless `--all` is set. - `--config ` - `--campaign ` - `--session ` - `--previous-session-id ` - `--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 `: inspect one manifest file. - `--config ` - `--campaign ` - `--session ` - `--session-id ` - `--previous-session-id ` ### `session validate` - `--config ` - `--campaign ` - `--session ` - `--session-id ` - `--previous-session-id ` ### `session init` - `--config `: required. - `--campaign `: required. - `--session-id `: required. - `--output `: 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 ` - `--date ` - `--title ` - `--audio-s3-prefix `: defaults to `audio/` when neither audio flag is provided. - `--audio-dir `: local audio directory; mutually exclusive with `--audio-s3-prefix`. - `--force`: overwrite existing local or remote target. ### `artifacts list` - `--config ` - `--campaign ` - `--session ` - `--session-id ` - `--previous-session-id ` - `--remote`: check remote availability for configured archive promotion destinations. ### `locks` - `--session-id `: required for list, add, and remove. - `--config `: optional explicit `pipeline.yml` path. - `--campaign `: optional explicit `campaign.yml` path. - `--session `: optional explicit `session.yml` path. - `--previous-session-id `: optional session template value. - `add `: add a remote lock for one artifact or transcript source. - `add --reason `: record an optional remote lock reason. - `add --force`: update the reason for an existing remote lock. - `remove `: remove one remote lock. ## Command Reference ### `run` Purpose: - Execute configured stages in canonical order. Syntax: ```bash narratio run [--config ] [--campaign ] [--session ] [--session-id ] [--previous-session-id ] [--force] [--artifacts ] ``` Success output: - `narratio run: session ; executed= skipped=; manifest=` 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 ] [--campaign ] [--session ] [--session-id ] [--previous-session-id ] [--force] ``` Success output includes: - `narratio plan: workdir prepared at ` - one line per stage (`: run|skip`) - `totals: run= skip=` 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 ] [--campaign ] [--session ] [--session-id ] [--previous-session-id ] [--force] [--artifacts ] ``` Success output: - `narratio resume: session has no remaining stages` - or `narratio resume: session ; executed= skipped=; manifest=` 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 narratio status [--config ] [--campaign ] [--session ] [--session-id ] [--previous-session-id ] ``` Manifest output includes: - `session_id: ` - `updated_at: ` - `stages:` entries (`- : `) 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 ] [--campaign ] [--session ] [--session-id ] [--previous-session-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 --campaign --session-id --output ./session.yml narratio session init --config --campaign --session-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 ] [--campaign ] [--session ] [--session-id ] [--previous-session-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=` 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 narratio locks add --session-id [--reason ] [--force] narratio locks remove --session-id ``` 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 ] [--campaign ] [--session ] [--session-id ] [--previous-session-id ] [--force] [--artifacts ] ``` Success output: - `narratio run-stage: stage= executed= skipped= force=; manifest=` `--artifacts` behavior: - accepted only when `` 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 ] [--campaign ] [--session ] [--session-id ] [--previous-session-id ] [--artifacts ] ``` Success output: - `narratio analyze: executed= skipped= force=true; manifest=` 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 ] [--campaign ] [--session ] [--session-id ] [--previous-session-id ] ``` Success output: - `narratio publish: executed= skipped= force=true; manifest=` 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 ] [--campaign ] [--session ] [--session-id ] [--previous-session-id ] [--dry-run] [--force] [--include-audio] ``` Success output (dry-run): - `Restore plan for /` - `Remote run: ` - `Would download: ` - `Would skip unchanged: ` - `Conflicts: ` Success output (non-dry-run): - `Restored session archive for /` - `Remote run: ` - `Downloaded: ` - `Skipped unchanged: ` - `Conflicts: ` 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 [--config ] [--campaign ] [--session ] [--previous-session-id ] [--dry-run] [--clear-cache] narratio clean --all [--config ] [--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 ``` Get manifest path from previous output: - `run`, `resume`, `run-stage`, `analyze`, and `publish` print `manifest=` 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.