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:

• version: print the Narratio build version.
• 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.
• config <subcommand>: validate, display, source-trace, or compare resolved pipeline configuration.

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>
• --profile <name>

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.
• --profile selects profiles/<name>.yml relative to the pipeline root. It may be supplied once; omitted, empty, and the exact name default select the base configuration, while an unknown named profile fails. The same selection applies to all common-flag commands, including regenerate-artifacts.
• 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

config validate, config show, config sources, and config diff

narratio config validate [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]
narratio config show [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]
narratio config sources [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]
narratio config diff <left-profile> <right-profile> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>]

These commands resolve the selected profile, defaults, ordinary paths, and—if a campaign is selected—the campaign-owned party. They neither discover or load a session nor create a workspace, manifest, run, lock, adapter, remote connection, or credential environment.

Campaign selection is optional for a pipeline without party-driven artifact families. A pipeline with scriptorium.artifact_families needs a selected or configured default campaign so Narratio can expand its concrete artifacts and publish rules. --campaign and --campaign-file remain mutually exclusive. Session, range, force, and artifact-execution flags are not accepted.

config validate writes a concise root-path, selected-profile (or none), and effective-digest summary after successful complete validation. config show writes one deterministic, secret-free YAML document containing defaulted and expanded concrete configuration. It omits ConfigKit directives, artifact family declarations, and runtime provenance.

config sources reports the same fully validated resolution without printing effective values. Its header identifies the root, ordered imports, selected profile and overlay, selected campaign, party source, and digest. The remaining tab-separated records are sorted as path, role, and source. Roles distinguish root, import, profile, centralized default, campaign, party, and generated family ownership. A generated party member has one family record and one party record at the same logical path. The output never reads or prints secret values.

config diff resolves both supplied profile names independently and compares their fully resolved, secret-free effective mappings. It does not accept --profile; the two positional names must be distinct, declared profiles. When party-driven families are present, both profiles must resolve to the same selected campaign and party. Use --campaign-file if profile-specific campaign configuration would otherwise select different files.

Equal profiles print no differences. Otherwise, sorted tab-separated records use one of these forms, with compact JSON values:

added    <path>    <right-value>
removed  <path>    <left-value>
changed  <path>    <left-value>    <right-value>

Mappings are flattened to their logical field paths; lists remain one atomic value. The command compares defaulted concrete artifacts and publish rules, not profile names, source-file layout, or formatting. It succeeds when differences are found, making it suitable for review and migration checks.

version

narratio version

Official release binaries report their exact Git tag. Binaries built directly from source without release linker metadata report dev.

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 cleanup, 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 the session manifest as the sole durable progress ledger. Each invocation also creates its run-local directory and returns an immediate command summary; neither creates another durable progress record.
• reports the resolved profile (or none) and effective configuration digest.

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

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]

This command selects only publish; it does not invoke cleanup. Use a normal full run to include configured cleanup, or run-stage cleanup to retry cleanup from valid publication evidence.

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 manual and pipeline-stage deletion scope.

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 and prints run/skip decisions for selected stages only without creating the local workdir or changing the manifest. Resume-capable selected stages are checked against durable evidence. The output includes the resolved profile (or none) and effective configuration digest without writing provenance or any manifest state. For analyze, the preview also lists explicit targets, prerequisite-only work, execution order, and reusable current artifacts with concise reasons. These artifact decisions come from the same reconciliation and work planner used by execution; the preview does not predict output identities.

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 independent remote 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. Current publish metadata reports published, carried_locked, locked_unpublished, optional_missing, and unselected; carried output lines include the run derived from their exact declared key, the key itself, and its declared destination. A separately displayed dest is the destination requested by the current configuration and may differ while an older declaration is locked.

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. Remote inspection uses exact commit declarations and displays the five current publish outcomes when recorded.

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 validates and reports independent remote locks sorted by source;
• add creates one lock and reports an existing lock unless --force is used;
• --force performs one generation-matched replacement and reports a concurrent change for operator retry; and
• remove is idempotent and reports when the source was not locked.

See Operations: Publish Locks for lock storage and publication behavior.

--artifacts Selection Rules

An artifact-family key selects all of its concrete character members. A concrete generated key selects only that member; mixed family and concrete selection is deduplicated and executed as concrete keys. The resulting plan and command output identify both the concrete key and, where applicable, its family and character ID.

• accepted on run, session plan, run-stage, analyze, and publish;
• repeatable and comma-separated values are combined, surrounding whitespace is removed, and duplicate names are collapsed;
• names must exist in pipeline.scriptorium.artifacts;
• empty entries are invalid;
• on run-stage, only analyze and publish accept the option.

Effects:

• selects explicit analyze targets; required configured prerequisites may be reused or rebuilt before them;
• 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

Regenerate post-transcript artifacts without publishing:

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

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.