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.
• 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.
• --previous-session-id is a strict expectation: the selected session file must contain the same previous_session_id.
• clean --all cannot be combined with campaign/session selectors.
• notification delivery is currently limited to the configured noop mode; see the configuration reference.

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;
• runs extract between trim and render; an omitted or disabled Notarius configuration records an explicit notarius_disabled self-skip;
• skips already-succeeded stages unless --force is set or a stage-specific resume check finds its durable result obsolete;
• continues interrupted or partially completed sessions by running non-succeeded stages;
• writes session and run manifests.

run-stage

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

Valid stage names:

• prepare
• transcribe
• merge
• polish
• normalize
• trim
• extract
• render
• 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 the selected session's local work and spool state;
• --all removes all local session work and spool state;
• cache remains unless --clear-cache is provided.

See Operations: Cleanup for deletion scope and post-publish cleanup behavior.

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, status for the pointer-selected remote commit and its declared published outputs.

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 an execution report;
• blocks unresolved conflicts. --force permits replacement only of eligible regular files.

See Operations: Restore Workflow for the default restore scope, report location, and conflict-handling workflow.

session artifacts

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

Lists effective built-in, configured Scriptorium, and configured extraction sources; reports planned, available, unavailable, and published state without reading payload bodies; and includes 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 reports the effective merge of static and remote locks;
• add/remove mutate only remote locks;
• static locks from pipeline config cannot be removed by CLI commands.

See Operations: Publish Locks for lock storage and precedence.

--artifacts Selection Rules

• accepted on run, 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 or explicitly configured narratio.extraction.<name> publish sources; and
• does not select or filter Notarius lanes.

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

Output And Exit Behavior

• Successful commands write their result or summary to standard output and exit with status 0.
• Command failures and invalid invocations write an error to standard error and exit with status 1.
• An unknown top-level command also prints the top-level usage summary to standard error.
• session restore --help prints its command-specific usage and exits with status 0.

Output is intended for operator inspection. Narratio does not currently offer a machine-readable CLI output mode; durable machine-readable state is recorded in manifests and reports described in Operations.