narratio/docs/cli.md

CLI

Shortest Useful Command

narratio run --session-id 2026-04-04

This command uses default config discovery for pipeline.yml and session.yml; both files must be discoverable unless you pass explicit --config and --session paths.

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 and print stage statuses from an existing manifest.
• run-stage: execute exactly one stage.

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.
• --session <path>: optional explicit session.yml path.
• --session-id <value>: session template variable value.
• --force: force stage execution.
• --artifacts <names>: analyze artifact keys to execute (repeatable or comma-separated).

plan

• --config <path>
• --session <path>
• --session-id <value>
• --force

resume

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

run-stage

• --config <path>
• --session <path>
• --session-id <value>
• --force
• --artifacts <names>: analyze artifact keys to execute (repeatable or comma-separated).
• positional <stage>: required stage name.

Valid stage names:

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

status

• --manifest <path>: required manifest path.

Command Reference

run

Purpose:

• Execute configured stages in canonical order.

Syntax:

narratio run [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force] [--artifacts <name[,name...]>]

Success output:

• narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>

Common failure cases:

• missing default config/session paths when flags omitted.
• invalid template/rendered session 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>] [--session <session.yml>] [--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/session discovery and validation failures as run.
• 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>] [--session <session.yml>] [--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/template/validation failures as run.
• manifest load errors when existing manifest is unreadable.
• invalid or unknown artifact selections.

status

Purpose:

• Inspect one manifest file without executing stages.

Syntax:

narratio status --manifest <manifest.json>

Success output includes:

• session_id: <id>
• updated_at: <timestamp>
• stages: entries (- <stage>: <status>)

Common failure cases:

• missing --manifest.
• unreadable or invalid manifest path.

run-stage

Purpose:

• Execute exactly one stage.

Syntax:

narratio run-stage [--config <pipeline.yml>] [--session <session.yml>] [--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.

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

Run only analyze stage with selected artifacts:

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

Diagnostic / Recovery Commands

Inspect stage status:

narratio status --manifest <manifest.json>

Get manifest path from previous output:

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