eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

CLI cleanup to consolidate session-related subcommands

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-22 22:09:17 -05:00
parent cee52aa092
commit 7657ec3ad6
31 changed files with 1341 additions and 830 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/troubleshooting.md
View File

@@ -6,7 +6,7 @@ Canonical operator troubleshooting guide for recurring implemented Narratio fail
## Config file discovery failure
Symptom:
- `run`, `plan`, `resume`, `run-stage`, or `restore` fails with config/session not found.
- `run`, `resume`, `run-stage`, `session plan`, or `session restore` fails with config/session not found.
Likely Cause:
- `pipeline.yml`, `campaign.yml`, or `session.yml` is missing from system discovery paths.
@@ -40,7 +40,7 @@ Likely Cause:
Diagnostics:
```bash
narratio plan --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session ./session.yml --session-id 2026-04-04
narratio session plan 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session ./session.yml
```
Safe Fix:
@@ -62,7 +62,7 @@ Likely Cause:
Diagnostics:
```bash
narratio plan --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04
narratio session plan 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml
```
Safe Fix:
@@ -84,7 +84,7 @@ Likely Cause:
Diagnostics:
```bash
narratio run --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --artifacts player_handout
narratio run 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --artifacts player_handout
```
Safe Fix:
@@ -95,22 +95,22 @@ Links:
- [docs/cli.md](./cli.md)
- [docs/config.md](./config.md)
## `run-stage --artifacts` on non-analyze stage
## `run-stage --artifacts` on unsupported stage
Symptom:
- `run-stage` fails with `--artifacts is only supported for stage "analyze"`.
- `run-stage` fails because `--artifacts` is only supported for `analyze` and `archive`.
Likely Cause:
- `--artifacts` was used with a non-`analyze` stage.
- `--artifacts` was used with a stage other than `analyze` or `archive`.
Diagnostics:
```bash
narratio run-stage --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --artifacts session_recap polish
narratio run-stage polish 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --artifacts session_recap
```
Safe Fix:
- use `--artifacts` only with `run-stage ... analyze`.
- use `--artifacts` only with `run-stage analyze ...` or `run-stage archive ...`.
Links:
- [docs/cli.md](./cli.md)
@@ -129,7 +129,7 @@ Likely Cause:
Diagnostics:
```bash
narratio plan --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04
narratio session plan 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml
```
Safe Fix:
@@ -153,8 +153,8 @@ Likely Cause:
Diagnostics:
```bash
narratio status --manifest /path/to/manifest.json
narratio run-stage --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --artifacts player_handout analyze
narratio session status 2026-04-04
narratio run-stage analyze 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --artifacts player_handout
```
Safe Fix:
@@ -168,22 +168,21 @@ Links:
## Manifest/status path failure
Symptom:
- `status` fails because manifest path is missing, unreadable, or invalid.
- `session status` fails because config/session state is missing, unreadable, or invalid.
Likely Cause:
- wrong manifest path.
- wrong session ID.
- wrong config/campaign/session file selected.
- manifest removed after cleanup.
- `--manifest` omitted.
Diagnostics:
```bash
narratio status --manifest /path/to/manifest.json
ls -l /path/to/manifest.json
narratio session status 2026-04-04
```
Safe Fix:
- use manifest path printed by `run`, `resume`, or `run-stage`.
- use the same session ID and config files that will be used for `run`, `resume`, or `run-stage`.
Links:
- [docs/cli.md](./cli.md)
@@ -192,7 +191,7 @@ Links:
## Session lock conflict (`.lock`)
Symptom:
- `run`, `resume`, `run-stage`, or `restore` fails with lock conflict for session workdir.
- `run`, `resume`, `run-stage`, or `session restore` fails with lock conflict for session workdir.
Likely Cause:
- another Narratio process is running same session.
@@ -217,7 +216,7 @@ Links:
## Restore remote current pointer or manifest missing
Symptom:
- `restore` fails with remote current pointer or current manifest errors.
- `session restore` fails with remote current pointer or current manifest errors.
Likely Cause:
- `current/run_id.txt` was never published.
@@ -227,7 +226,7 @@ Likely Cause:
Diagnostics:
```bash
narratio restore --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --dry-run
narratio session restore 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --dry-run
```
Safe Fix:
@@ -241,20 +240,20 @@ Links:
## Restore manifest identity mismatch
Symptom:
- `restore` fails because remote manifest session or campaign does not match requested values.
- `session restore` fails because remote manifest session or campaign does not match requested values.
Likely Cause:
- wrong `--session-id` or wrong session config selected.
- wrong positional session ID or wrong session config selected.
- archive prefix points to a different campaign/session.
Diagnostics:
```bash
narratio restore --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --dry-run
narratio session restore 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --dry-run
```
Safe Fix:
- use the correct session config and `--session-id`.
- use the correct session config and positional session ID.
- verify campaign/session identity in local config before restore.
Links:
@@ -264,7 +263,7 @@ Links:
## Restore conflict without `--force`
Symptom:
- `restore` fails with `restore conflict` and conflict counts.
- `session restore` fails with `restore conflict` and conflict counts.
Likely Cause:
- local durable file differs from remote file for one or more planned restore paths.
@@ -272,7 +271,7 @@ Likely Cause:
Diagnostics:
```bash
narratio restore --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 --dry-run
narratio session restore 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --dry-run
```
Safe Fix:
@@ -342,7 +341,7 @@ Likely Cause:
Diagnostics:
```bash
narratio run-stage --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 prepare
narratio run-stage prepare 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml
```
Safe Fix:
@@ -365,8 +364,8 @@ Likely Cause:
Diagnostics:
```bash
narratio status --manifest /path/to/manifest.json
narratio run-stage --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml --session-id 2026-04-04 archive
narratio session status 2026-04-04
narratio run-stage archive 2026-04-04 --config /path/to/pipeline.yml --campaign /path/to/campaign.yml --session /path/to/session.yml
```
Safe Fix: