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 all or one contiguous range of the canonical stage order.
• regenerate-artifacts <session_id>: force-run extraction through analysis.
• 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> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]

Behavior:

• evaluates one inclusive contiguous range of the canonical stage order;
• defaults an omitted --from to prepare and an omitted --through to notify, so omitting both retains full-pipeline behavior;
• rejects unknown endpoints and a --from endpoint after --through;
• runs render before extract; 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;
• applies --force only to stages in the selected range;
• rejects repeated --from, --through, or --force options, including --name=value spellings;
• continues interrupted or partially completed sessions by running non-succeeded stages;
• writes session and run manifests.

When --artifacts is present, the selected range must contain analyze or publish. Either consumer is sufficient, including a one-stage range.

regenerate-artifacts

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

Exactly equivalent to:

narratio run <session_id> --force --from extract --through analyze [caller options]

The command always reruns extraction. Analysis rebuilds the selected configured artifacts and any prerequisites required by those targets; without --artifacts, it uses the normal default analysis selection. Publish and notify never run. Common session/configuration options and repeatable artifact values pass through unchanged.

Because the expansion owns --force, --from, and --through, callers cannot supply those options. The shared run parser reports them as duplicate singleton flags. The alias has no private execution options or behavior, and runtime diagnostics may identify the operation as run.

run-stage

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

Valid stage names:

• prepare
• transcribe
• merge
• polish
• normalize
• trim
• render
• extract
• 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> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]

Uses the same inclusive bounds, endpoint validation, force scope, and artifact selection contract as run. It validates config, prepares local workdir layout, and prints run/skip decisions for selected stages only.

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, session plan, 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.