narratio/docs/cli.md

CLI

Shortest Useful Command

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

This uses default config discovery for pipeline.yml and session.yml; both files must be discoverable for this command to run.

Command Overview

Implemented commands:

• run: execute the full stage plan and persist manifest state.
• plan: validate config, prepare workdir, and print run/skip decisions.
• resume: continue from the first non-succeeded stage in the manifest.
• status: read and print stage statuses from an existing manifest file.
• run-stage: execute exactly one selected stage.

Unknown commands print usage (Usage: narratio <run|plan|status|resume|run-stage>) and exit non-zero.

For configuration field details, see docs/config.md. For operational lifecycle details, see docs/operations.md.

Complete Flag Reference

run

• --config <path>: optional explicit pipeline.yml path; if omitted, default locations are searched.
• --session <path>: optional explicit session.yml path; if omitted, default locations are searched.
• --session-id <value>: session template variable value for session.yml rendering.
• --force: force stage execution (prevents skip of already-succeeded stages).

plan

• --config <path>
• --session <path>
• --session-id <value>
• --force: show forced run decisions instead of normal skip behavior.

resume

• --config <path>
• --session <path>
• --session-id <value>
• --force: run full stage order rather than starting at first non-succeeded stage.

run-stage

• --config <path>
• --session <path>
• --session-id <value>
• --force
• 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:

• Validate configuration and execute all stages in canonical order.

Syntax:

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

Success output:

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

Common failure cases:

• no pipeline config found in default search paths when --config is omitted.
• no session config found in default search paths when --session is omitted.
• invalid flags or unexpected positional arguments.
• config/template/validation errors.

plan

Purpose:

• Validate config, load secrets (if configured), prepare workspace layout, and print per-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 discovery, template, and validation failures as run.
• secrets directory read failures when pipeline.secrets.env_dir is configured.

resume

Purpose:

• Continue execution from manifest state for the same session.

Syntax:

narratio resume [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force]

Success output:

• either 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 an existing manifest is unreadable.

status

Purpose:

• Inspect an existing manifest file without running stages.

Syntax:

narratio status --manifest <manifest.json>

Success output includes:

• session_id: <id>
• updated_at: <timestamp>
• stages: section with - <stage>: <status> entries.

Common failure cases:

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

run-stage

Purpose:

• Execute exactly one stage from the supported stage set.

Syntax:

narratio run-stage [--config <pipeline.yml>] [--session <session.yml>] [--session-id <id>] [--force] <stage>

Success output:

• narratio run-stage: stage=<name> executed=<n> skipped=<n> force=<true|false>; manifest=<path>

Common failure cases:

• missing stage positional argument.
• unknown stage name.
• same discovery/template/validation failures as run.

Common Workflows

Default-discovery run:

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

Explicit config/session run:

narratio run --config /etc/narratio/pipeline.yml --session ./session.yml --session-id 2026-04-04

Plan before run:

narratio plan --config /etc/narratio/pipeline.yml --session ./session.yml --session-id 2026-04-04

Resume interrupted work:

narratio resume --config /etc/narratio/pipeline.yml --session ./session.yml --session-id 2026-04-04

Run one stage:

narratio run-stage --config /etc/narratio/pipeline.yml --session ./session.yml --session-id 2026-04-04 polish

Diagnostic / Recovery Commands

Read stage status from a manifest:

narratio status --manifest <manifest.json>

How to get manifest path:

• run, resume, and run-stage success output includes manifest=<path>.
• use that path with status for direct inspection.