narratio/docs/cli.md

CLI

Shortest Useful Command

narratio run 2026-04-04

This runs the full pipeline for the given session ID using default config discovery and campaign selection.

Command Overview

Top-level commands:

• run <session_id>: execute the pipeline.
• resume <session_id>: continue from first non-succeeded stage.
• run-stage <stage> <session_id>: execute exactly one stage.
• analyze <session_id>: force-rerun analyze stage.
• publish <session_id>: force-rerun publish stage.
• clean <session_id>|--all: remove local workspace/spool state.
• session <subcommand>: session-scoped helper commands.

Session subcommands:

• session init <session_id>
• session plan <session_id>
• session validate <session_id>
• session status <session_id>
• session restore <session_id>
• session artifacts <session_id>
• session locks <session_id>
• session locks add <session_id> <source>
• session locks remove <session_id> <source>

Common Flags

Most session-aware commands accept:

• --config <pipeline.yml>
• --campaign <id>
• --campaign-file <campaign.yml>
• --session <session.yml>
• --previous-session-id <id>

--campaign and --campaign-file are mutually exclusive.

Command Reference

run

narratio run <session_id> [--force] [--artifacts <name[,name...]>] [...common flags]

Runs stages in canonical order and writes manifest state.

resume

narratio resume <session_id> [--force] [--artifacts <name[,name...]>] [...common flags]

Starts at the first non-succeeded stage from the session manifest.

run-stage

narratio run-stage <stage> <session_id> [--force] [--artifacts <name[,name...]>] [...common flags]

Valid stage names:

• prepare
• transcribe
• merge
• polish
• normalize
• trim
• analyze
• publish
• notify

--artifacts is accepted only for analyze and publish.

analyze

narratio analyze <session_id> [--artifacts <name[,name...]>] [...common flags]

Equivalent to narratio run-stage analyze <session_id> --force.

publish

narratio publish <session_id> [--artifacts <name[,name...]>] [...common flags]

Equivalent to narratio run-stage publish <session_id> --force.

clean

narratio clean <session_id> [--dry-run] [--clear-cache] [...common flags]
narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]

• session mode deletes {workspace.root}/work/{campaign}/{session_id} and {spool.root}/{campaign}/{session_id}.
• --all deletes all session work and spool children.
• cache is preserved unless --clear-cache is passed.

session plan

narratio session plan <session_id> [--force] [...common flags]

Validates config and session inputs, prepares workdir layout, and prints stage run/skip decisions.

session validate

narratio session validate <session_id> [...common flags]

Read-only preflight checks for config, inputs, audio availability, previous-session requirements, publish outputs, and effective locks.

session status

narratio session status <session_id> [...common flags]

Shows local manifest state, remote current state (when storage is configured), published-output availability, and effective locks.

session init

narratio session init <session_id> --output ./session.yml
narratio session init <session_id> --remote
narratio session init <session_id> --remote --force

Flags:

• --output <path> or --remote (exactly one is required)
• --previous-session-id <id>
• --date <date>
• --title <title>
• --audio-dir <path>
• --audio-s3-prefix <prefix>
• --force
• common config/campaign flags

session restore

narratio session restore <session_id> [--dry-run] [--force] [--include-audio] [...common flags]

Restores durable local session files from committed remote current state.

Default restore scope:

• manifest.json
• transcripts/**
• artifacts/**
• previous/** when required by configured previous-session artifact inputs

audio/** is restored only when --include-audio is set.

session artifacts

narratio session artifacts <session_id> [--remote] [...common flags]

Lists built-in sources, configured artifact sources, previous-session sources, publish output rules, and lock status. With --remote, includes remote published-state markers.

session locks

narratio session locks <session_id> [...common flags]
narratio session locks add <session_id> <source> [--reason <text>] [--force] [...common flags]
narratio session locks remove <session_id> <source> [...common flags]

• list mode prints effective locks from static pipeline.publish.locks and remote {session_prefix}/locks.yml.
• add/remove mutate only the remote lock store.
• static pipeline locks cannot be removed by lock commands.

--artifacts Rules

• accepted on run, resume, run-stage, analyze, and publish.
• on run-stage, only valid for analyze and publish.
• filters configured analyze artifact execution.
• filters configured pipeline.publish.outputs entries for narratio.artifact.<key> sources.
• does not suppress built-in transcript/bounds publish outputs.
• does not imply --force for run, resume, or run-stage.

Common Workflows

Run full pipeline:

narratio run 2026-04-04

Run only selected analyze artifacts:

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

Force analyze only:

narratio analyze 2026-04-04 --artifacts player_handout

Force publish only:

narratio publish 2026-04-04

Restore preview then apply:

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