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.

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

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. 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>: expected session identifier and remote session lookup value.
• --previous-session-id <value>: expected previous session identifier.
• --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.

analyze

• --config <path>
• --campaign <path>
• --session <path>
• --session-id <value>
• --previous-session-id <value>
• --artifacts <names>: analyze artifact keys to execute (repeatable or comma-separated).

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

publish

• --config <path>
• --campaign <path>
• --session <path>
• --session-id <value>
• --previous-session-id <value>

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

clean

• --session-id <value>: required for session cleanup unless --all is set.
• --config <path>
• --campaign <path>
• --session <path>
• --previous-session-id <value>
• --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 <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>: optional explicit pipeline.yml path.
• --campaign <path>: optional explicit campaign.yml path.
• --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.

When campaign.yml sets session_template_file, session init renders that template before writing the concrete session file. Template variables are supplied by these flags: --session-id, --previous-session-id, --date, --title, --audio-s3-prefix, and --audio-dir.

artifacts list

• --config <path>
• --campaign <path>
• --session <path>
• --session-id <value>
• --previous-session-id <value>
• --remote: check remote availability for configured archive promotion destinations.

locks

• --session-id <value>: required for list, add, and remove.
• --config <path>: optional explicit pipeline.yml path.
• --campaign <path>: optional explicit campaign.yml path.
• --session <path>: optional explicit session.yml path.
• --previous-session-id <value>: optional expected previous session identifier.
• add <source>: add a remote lock for one artifact or transcript source.
• add --reason <text>: record an optional remote lock reason.
• add --force: update the reason for an existing remote lock.
• remove <source>: remove one remote lock.

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.
• templated session.yml; run narratio session init to generate concrete YAML.
• concrete session identity 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 and 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.
• 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:

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 concrete session.yml locally or in object storage.

Syntax:

narratio session init --session-id <id> --output ./session.yml
narratio session init --session-id <id> --remote
narratio session init --config <pipeline.yml> --campaign <campaign.yml> --session-id <id> --remote

Behavior:

• exactly one of --output or --remote is required.
• --config and --campaign are optional overrides; omitted values use normal default config discovery.
• 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.

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

locks

Purpose:

• Inspect and mutate source-based archive promotion locks for one session.

Syntax:

narratio locks --session-id <id>
narratio locks add --session-id <id> [--reason <text>] [--force] <source>
narratio locks remove --session-id <id> <source>

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:

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:

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.

analyze

Purpose:

• Force-rerun the analyze stage.
• Provide a shorter equivalent for narratio run-stage --force analyze.

Syntax:

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

Success output:

• narratio analyze: executed=<n> skipped=<n> force=true; manifest=<path>

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:

narratio publish [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>] [--previous-session-id <id>]

Success output:

• narratio publish: executed=<n> skipped=<n> force=true; manifest=<path>

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:

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

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

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:

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

Force-rerun analyze with selected artifacts:

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

Force-rerun archive publishing:

narratio publish --session-id 2026-04-04

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 analyze --session-id 2026-04-04

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

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

Reset local state before testing restore:

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:

narratio clean --all

Diagnostic / Recovery Commands

Inspect stage status:

narratio status --manifest <manifest.json>

Get manifest path from previous output:

• run, resume, run-stage, analyze, and publish 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.