narratio/docs/cli.md

CLI

Shortest Useful Command

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.
• 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 effective archive promotion locks.
• lock: add or update a remote session lock.
• unlock: remove a remote session lock.

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>: 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 promoted remote object availability.

locks, lock, unlock

• --config <path>
• --campaign <path>
• --session <path>
• --session-id <value>
• --previous-session-id <value>
• lock <source> positional source ID.
• lock --reason <text> optional remote lock reason.
• lock --force updates an existing remote lock.
• unlock <source> positional source ID.

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

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, or inspect configured local/remote state for a session.

Syntax:

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

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:

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:

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.

locks, lock, and unlock

Purpose:

• Inspect and mutate source-based archive promotion locks.

Syntax:

narratio locks [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>]
narratio lock [flags] <source>
narratio unlock [flags] <source>

Behavior:

• static locks from pipeline.archive.locks and remote locks from {session_prefix}/locks.yml are merged.
• static locks win when sources duplicate remote locks.
• lock writes or updates only remote locks.
• unlock removes only remote locks and cannot remove static pipeline locks.
• lock --force is required to update an existing remote lock reason.

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.