narratio/docs/cli.md

CLI

Shortest Useful Command

narratio run --session-id 2026-04-04

This command uses default 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.

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.
• restore: restore durable local session state from the committed remote archive state.

Unknown commands print usage and exit non-zero.

For config semantics, see docs/config.md. For operator lifecycle and recovery, see docs/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.

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.

status

• --manifest <path>: required manifest path.

Command Reference

run

Purpose:

• Execute configured stages in canonical order.

Syntax:

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 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:

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:

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 without executing stages.

Syntax:

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:

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.

restore

Purpose:

• Restore durable session state (manifest.json, transcripts/**, artifacts/**, previous/**, and optional audio/**) from the committed remote archive current state.

Syntax:

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.
• local conflicts without --force.
• session lock conflict.

Common Workflows

Default-discovery run:

narratio run --session-id 2026-04-04

Run only selected analyze artifacts:

narratio run --session-id 2026-04-04 --artifacts session_recap,player_handout

Resume with selected analyze artifacts:

narratio resume --session-id 2026-04-04 --artifacts player_handout

Run only analyze stage with selected artifacts:

narratio run-stage --session-id 2026-04-04 --artifacts player_handout analyze

Preview restore actions without writes:

narratio restore --session-id 2026-04-04 --dry-run

Restore and then force analyze:

narratio restore --session-id 2026-04-04
narratio run-stage --session-id 2026-04-04 --force analyze

Rehydrate canonical previous-session inputs after artifact-input changes:

narratio run-stage --session-id 2026-04-04 --force prepare

Diagnostic / Recovery Commands

Inspect stage status:

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.