narratio/docs/cli.md

CLI Reference

Shortest Useful Command

narratio run 2026-04-04

This runs the canonical full pipeline for session 2026-04-04.

Command Overview

Top-level commands:

• run <session_id>: run full stage order.
• resume <session_id>: continue from first non-succeeded stage.
• run-stage <stage> <session_id>: run one stage.
• analyze <session_id>: force-run analyze.
• publish <session_id>: force-run publish.
• clean <session_id> or clean --all: remove local work/spool state.
• session <subcommand>: session 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 Config Flags

Most session-aware commands accept:

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

Rules:

• --campaign and --campaign-file are mutually exclusive.
• --session is not used by session init.
• if both positional <session_id> and --session-id are provided, values must match.
• clean --all cannot be combined with campaign/session selectors.

Session ID Input Rules

Session-aware commands accept one of these forms:

• positional session ID: ... <session_id>
• compatibility flag: ... --session-id <session_id>

When both are present, command parsing requires an exact match.

Commands with additional positionals keep their command-specific order:

• run-stage <stage> <session_id> or run-stage <stage> --session-id <session_id>
• session locks add <session_id> <source> or session locks add --session-id <session_id> <source>
• session locks remove <session_id> <source> or session locks remove --session-id <session_id> <source>

Command Reference

run

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

Behavior:

• evaluates full stage order;
• skips already-succeeded stages unless --force is set;
• writes session and run manifests.

resume

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

Behavior:

• when not forced, starts at first non-succeeded stage in manifest order;
• with --force, reevaluates the selected stage list as runnable.

run-stage

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

Valid stage names:

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

Rules:

• --artifacts is accepted only for analyze and publish stage targets.

analyze

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

Equivalent to:

narratio run-stage analyze <session_id> --force [...common config flags]

publish

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

Equivalent to:

narratio run-stage publish <session_id> --force [...common config flags]

clean

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

Behavior:

• session mode removes:
  • {workspace.root}/work/{campaign}/{session_id}
  • {spool.root}/{campaign}/{session_id}
• --all removes:
  • {workspace.root}/work/*
  • direct children under {spool.root}
• cache remains unless --clear-cache is provided.

session plan

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

Validates config, prepares local workdir layout, and prints run/skip decisions for each stage.

session validate

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

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

session status

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

Prints local manifest state and, when storage is available, remote current-state and published-output status.

session init

narratio session init <session_id> --output ./session.yml [options]
narratio session init <session_id> --remote [options]

Required target selection:

• exactly one of:
  • --output <path>
  • --remote

Options:

• --config <pipeline.yml>
• --campaign <id> or --campaign-file <campaign.yml>
• --previous-session-id <id>
• --date <YYYY-MM-DD>
• --title <text>
• --audio-dir <path>
• --audio-s3-prefix <prefix>
• --force

Rules:

• --audio-dir and --audio-s3-prefix are mutually exclusive.
• if campaign session_template_file is configured, session init renders it.
• generated session YAML must be concrete (no unresolved {{ ... }} placeholders).

session restore

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

Behavior:

• discovers committed remote current state;
• plans local restores;
• writes reports/restore-latest.json on execution;
• blocks conflicting overwrites unless --force is set.

Default restore scope:

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

audio/** is included only with --include-audio.

session artifacts

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

Lists effective built-in and configured artifact sources, publish rules, lock state, and optional remote published-state availability.

session locks

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

Behavior:

• list mode merges static pipeline.publish.locks with remote {session_prefix}/locks.yml;
• add/remove mutate only remote locks;
• static locks from pipeline config cannot be removed by CLI commands.

--artifacts Selection Rules

• accepted on run, resume, run-stage, analyze, and publish;
• names must exist in pipeline.scriptorium.artifacts;
• empty entries are invalid;
• repeated names are deduplicated.

Effects:

• filters analyze execution to selected configured artifacts;
• filters publish rules that source narratio.artifact.<name>;
• does not filter built-in transcript/bounds publish sources.

Common Workflows

Run full pipeline:

narratio run 2026-04-04

Dry-run restore plan:

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

Generate a concrete session file from template/default structure:

narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"

Force publish only:

narratio publish 2026-04-04