# CLI

## Shortest Useful Command

```bash
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](./config.md). For operational lifecycle details, see [docs/operations.md](./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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
narratio run --session-id 2026-04-04
```

Explicit config/session run:

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

Plan before run:

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

Resume interrupted work:

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

Run one stage:

```bash
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:

```bash
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.