narratio/docs/cli.md

CLI

Shortest Useful Command

narratio run 2026-04-04

This command uses default system discovery for pipeline.yml, the pipeline default campaign ID, and local session.yml. If local session discovery misses and S3 storage is configured, the positional session ID loads remote session.yml from the canonical session prefix.

Default pipeline and session discovery checks system config locations only. Pass --config, --campaign-file, and --session to use files from the current working directory. Pass --campaign <id> to select a campaign from pipeline.campaigns.root.

Ordinary local and remote session.yml files must be concrete YAML. Templates belong to narratio session init, which renders a configured campaign template before writing the concrete file.

Command Overview

Top-level commands:

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

Session subcommands:

• session init <session_id>: create local or remote session.yml.
• session validate <session_id>: run read-only preflight checks.
• session status <session_id>: inspect local/remote session state.
• session plan <session_id>: validate config, prepare workspace layout, and print stage run/skip decisions.
• session restore <session_id>: restore durable local state from committed remote archive state.
• session artifacts <session_id>: list effective artifact source IDs.
• session locks <session_id>: list archive promotion locks.
• session locks add <session_id> <source>: add or update a remote lock.
• session locks remove <session_id> <source>: remove a remote 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.

Common Flags

Most session-aware commands accept:

• --config <path>: optional explicit pipeline.yml path.
• --campaign <id>: optional campaign ID selector.
• --campaign-file <path>: optional explicit campaign.yml path.
• --session <path>: optional explicit concrete session.yml path.
• --previous-session-id <value>: expected previous session identifier.

The positional <session_id> is required even when --session is provided. It is used as the expected session identity and as the remote session lookup value when local session discovery misses.

Command Reference

run

narratio run <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>]

Purpose:

• Execute configured stages in canonical order.

Success output:

• narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>

Common failure cases:

• missing system default config/session paths when flags are omitted.
• missing selected campaign under pipeline.campaigns.root.
• missing local session plus missing/unavailable remote session.yml.
• templated session.yml; run narratio session init to generate concrete YAML.
• concrete session identity mismatch.
• unknown configured artifact key in --artifacts.

resume

narratio resume <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>]

Purpose:

• Continue from session-manifest stage status.

Success output:

• narratio resume: session <session_id> has no remaining stages
• or narratio resume: session <session_id>; executed=<n> skipped=<n>; manifest=<path>

run-stage

narratio run-stage <stage> <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--force] [--artifacts <name[,name...]>]

Valid stage names:

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

Success output:

• narratio run-stage: stage=<name> executed=<n> skipped=<n> force=<true|false>; manifest=<path>

--artifacts is accepted only for analyze and archive.

analyze

narratio analyze <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--artifacts <name[,name...]>]

Purpose:

• Force-rerun the analyze stage.
• Shorter equivalent for narratio run-stage analyze <session_id> --force.

analyze is force-by-design and does not accept --force.

publish

narratio publish <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--artifacts <name[,name...]>]

Purpose:

• Force-rerun the archive stage.
• Shorter equivalent for narratio run-stage archive <session_id> --force.

publish is force-by-design and does not accept --force or a stage positional argument.

clean

narratio clean <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <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.

session plan

narratio session plan <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--force]

Purpose:

• Validate config, load secrets if configured, prepare workdir, and print stage run/skip decisions.

Success output includes:

• narratio session plan: workdir prepared at <path>
• one line per stage (<stage>: run|skip)
• totals: run=<n> skip=<n>

session status

narratio session status <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>]

Output includes:

• session ID, campaign, workspace, and session config source.
• local manifest state when present.
• remote current archive state when storage is configured.
• catalog-based promoted output availability for expected transcript and artifact sources.
• effective archive locks and conservative next actions.

session validate

narratio session validate <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--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

narratio session init <session_id> --output ./session.yml
narratio session init <session_id> --remote
narratio session init <session_id> --config <pipeline.yml> --campaign icewind --remote
narratio session init <session_id> --config <pipeline.yml> --campaign-file ./campaign.yml --remote

Additional flags:

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

Behavior:

• exactly one of --output or --remote is required.
• --config, --campaign, and --campaign-file are optional overrides; omitted campaign selection uses pipeline.campaigns.default_campaign_id.
• --campaign <id> selects a campaign under pipeline.campaigns.root.
• --campaign-file <path> loads an explicit campaign file.
• if campaign.yml sets session_template_file, the template path is resolved relative to campaign.yml and rendered from init flags.
• if no session template is configured, a minimal concrete session file is generated directly.
• template variables must be supplied by matching flags, and supplied template-related flags must be used by the template.
• 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.

session restore

narratio session restore <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--dry-run] [--force] [--include-audio]

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.
• audio/** is restored only with --include-audio.

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.

session artifacts

narratio session artifacts <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--remote]

Purpose:

• List built-in, configured, previous-session, promoted, and locked artifact sources.

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

session locks

narratio session locks <session_id> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>]
narratio session locks add <session_id> <source> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--reason <text>] [--force]
narratio session locks remove <session_id> <source> [--config <pipeline.yml>] [--campaign <id>] [--campaign-file <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>]

Behavior:

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

Common Workflows

Default-discovery run:

narratio run 2026-04-04

Run only selected analyze artifacts:

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

Resume with selected analyze artifacts:

narratio resume 2026-04-04 --artifacts player_handout

Force-rerun analyze with selected artifacts:

narratio analyze 2026-04-04 --artifacts player_handout

Force-rerun archive publishing:

narratio publish 2026-04-04

Preview restore actions without writes:

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

Restore and then force analyze:

narratio session restore 2026-04-04
narratio analyze 2026-04-04

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

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

Reset local state before testing restore:

narratio clean 2026-04-04 --dry-run
narratio clean 2026-04-04
narratio session restore 2026-04-04 --include-audio

Clean all local sessions while keeping cached S3 audio:

narratio clean --all

--artifacts and --force

• --artifacts filters which configured artifacts are executable when analyze runs and which configured artifact promotions archive publishes.
• --artifacts does not imply --force.
• if analyze is already succeeded and --force is not set, runner-level skip still applies.
• --artifacts does not suppress built-in transcript or bounds promotions.