CLI Reference
The stepbook command is the headless interface to a stepbook project — used by both humans and agents. Every command runs against the project discovered from the current directory (see Config).
Global
stepbook <command> [options]- Version:
-v, --version - Help:
stepbook --help, orstepbook <command> --help
Output modes
Most commands accept two mutually exclusive output flags:
--json— a machine-readable versioned envelope on stdout.--md— write a Markdown report tostate/reports/and print its path.
With no flag, output is human-readable and colored. In --json/--md mode, info-level chatter is redirected to stderr so stdout stays clean.
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | Runtime failure — a step threw, a check failed, output unreadable. |
2 | Config / usage error — bad flag combination, missing config, unknown step. |
Addressing a unit in a run
A run's trajectory nodes are keyed by unit name when a unit runs once, or <unit>#<index> when it repeats (e.g. one node per agent turn). Commands that take a unit name — q <unit>, variance <unit>, snapshot-diff <unit> — resolve it by name against the trajectory.
init
Scaffold a new stepbook project (config + sample step + sample input).
stepbook init
stepbook init --dir my-pipeline --name my-pipeline| Option | Description |
|---|---|
-d, --dir <path> | Target directory (default .). |
-n, --name <name> | Pipeline name (default: directory name). |
--force | Overwrite existing files. |
--json | Machine-readable output. |
add-step alias: add
Generate a new step skeleton. Placed anywhere matching your steps glob.
stepbook add-step extract --type llm
stepbook add-step summarize -t derive -d steps/stage-2| Argument / Option | Description |
|---|---|
<name> (required) | Step key — becomes the file basename and the defineStep name. |
-t, --type <type> | input | parse | llm | derive | eval (default parse). |
-d, --dir <path> | Destination dir relative to project root (default steps). |
--force | Overwrite an existing file. |
--json | Machine-readable output. |
run
Execute the pipeline entrypoint once and persist a run blob. Prints the trajectory tree — the units the entrypoint composed, in call order.
stepbook run # canonical input
stepbook run inputs/hello.json # specific input
stepbook run --just analyze --case Empty # one unit against a named case, isolated
stepbook run --no-cache --json| Argument / Option | Description |
|---|---|
[input] | Input file (relative to inputs/ or absolute). Optional. |
-j, --just <step> | Run one unit in isolation (pair with --case). |
--case <name> | With --just, run that unit against a named case only. |
-f, --from <step> | Force re-execution starting at this step. |
-t, --to <step> | Stop execution after this step. |
--till <step> | Shorthand for --from <first> --to <step>. |
--no-cache | Bypass the snapshot cache (re-execute everything). |
--json | Machine-readable envelope. |
--md | Write a Markdown report to state/reports/. |
--just <step> --case <name> runs a single unit against one case — no cache, no persisted blob — for tight iteration on one unit.
In --json mode the data payload is { pipeline, ts, git_sha, blob, totals, root }, where root is the run's TrajectoryNode tree. See The Cache for how --from and --no-cache interact with replay.
check
CI-friendly: run the pipeline and exit non-zero if any check fails.
stepbook check
stepbook check --cases # run every unit's cases in isolation
stepbook check --step analyze # only this step, with cached upstream
stepbook check --json | jq '.data.totals.fail'| Argument / Option | Description |
|---|---|
[input] | Input file (relative to inputs/ or absolute). |
-s, --step <key> | Check only this step (with cached upstream). |
--cases | Run every unit's cases in isolation, not the pipeline. |
--json | Machine-readable envelope. |
--md | Write a Markdown report. |
Exits 1 if any assertion fails — this is what makes check the CI verb. In --json mode the data payload carries totals, failed, and the run's trajectory root tree.
diff
Compare two whole runs — assertion flips plus a drift summary.
stepbook diff # previous vs latest
stepbook diff --from latest-3 --to latest| Option | Description |
|---|---|
--from <selector> | Older run selector (default previous). |
--to <selector> | Newer run selector (default latest). |
--json | Machine-readable envelope. |
--md | Write a Markdown report. |
Run selectors: latest, previous, latest-N (e.g. latest-3), all, or a timestamp/SHA substring.
snapshot-diff alias: sdiff
Compare a single step's output between two run blobs.
stepbook snapshot-diff analyze
stepbook snapshot-diff analyze --fields
stepbook snapshot-diff analyze --open
stepbook snapshot-diff analyze --across-last 5| Argument / Option | Description |
|---|---|
<step> (required) | Step key to diff. |
--from <selector> | Older run selector (default previous). |
--to <selector> | Newer run selector (default latest). |
--fields | Show per-field drift breakdown. |
--open | Open both snapshots in $STEPBOOK_DIFF_CMD (default code --diff). |
--across-last <N> | Diff every adjacent pair across the last N runs (overrides --from/--to). |
--json | Machine-readable envelope. |
--md | Write a Markdown report. |
variance alias: var
Measure run-to-run variance for a step. See Drift & Stability.
stepbook variance classify -n 10
stepbook variance classify --across-last 5 --show-clusters
stepbook variance classify -n 10 --embed 0.9| Argument / Option | Description |
|---|---|
<step> (required) | Step key to measure. |
-n, --runs <N> | Fresh sampling: re-execute the step N times. |
--across-last <N> | Historical: use the last N persisted runs (default 5). |
--show-clusters | List identical-output clusters with representatives. |
--embed [threshold] | Cluster via pipeline.ts's exported embed (default threshold 0.85). |
--json | Machine-readable envelope. |
--md | Write a Markdown report. |
q alias: query
Run a query against a step's output. Queries are a structured YAML surface that compiles to JSONata; pass --jsonata to write a raw JSONata expression instead. See StepQL.
stepbook q analyze "select: longWords" # YAML query (default)
stepbook q analyze query.yaml # multi-line query from a file
stepbook q analyze "$.longWords[$length($) > 8]" --jsonata --json
stepbook q analyze "select: longWords" --explain # show the compiled JSONata
stepbook q analyze --saved my-query
stepbook q analyze "select: density" --save density-check| Argument / Option | Description |
|---|---|
<step> (required) | Step key whose output to query. |
[query] | A YAML query, or a path to a .yaml/.yml file (omit with --saved). |
--jsonata | Treat <query> as a raw JSONata expression instead of YAML. |
--explain | Print the compiled JSONata and exit (don't run). |
-r, --run <selector> | Run selector (default latest). |
-f, --format <fmt> | Human-mode output: table | json | raw (default table). |
--save <name> | Save this query under <name> for the step. |
--saved <name> | Recall a previously saved query (omit the positional query). |
--json | Machine-readable envelope (overrides --format). |
--md | Write a Markdown report. |
--save and --saved are mutually exclusive.
list alias: ls
List persisted runs, newest first.
stepbook list
stepbook list --limit 50 --json| Option | Description |
|---|---|
-n, --limit <N> | Max runs to show (default 20). |
--json | Machine-readable envelope. |
--md | Write a Markdown report. |
list-steps alias: steps
List discovered units. Columns: KEY, TYPE (and SOURCE with -v).
stepbook list-steps
stepbook list-steps --verbose # include each unit's source file path| Option | Description |
|---|---|
-v, --verbose | Include each unit's source file path. |
--json | Machine-readable envelope. |
cases alias: cs
List a unit's named cases (its fixtures / "stories"), or all units' cases.
stepbook cases
stepbook cases analyze| Argument / Option | Description |
|---|---|
[step] | Only show cases for this unit (default: all). |
--json | Machine-readable envelope. |
save-case
Snapshot a unit's recorded input from a run into cases/<step>/<name>.json, so you can replay it with run --just <step> --case <name>.
stepbook save-case analyze regression
stepbook save-case analyze regression --from-run 2026-06-30T12:00:00.000Z| Argument / Option | Description |
|---|---|
<step> (required) | Unit whose recorded input to snapshot. |
<name> (required) | Case name — becomes cases/<step>/<name>.json. |
--from-run <ts> | Run timestamp to read from (default: last run). |
--json | Machine-readable envelope. |
The input is read from the unit's trajectory node in the chosen run, so the unit must have been invoked in that run.
prune
Delete old run blobs. Requires at least one of --keep-last or --older-than.
stepbook prune --keep-last 20
stepbook prune --older-than 30d --dry-run| Option | Description |
|---|---|
--keep-last <N> | Keep the N newest runs, prune the rest. |
--older-than <duration> | Prune runs older than e.g. 30d, 2w, 12h. |
--dry-run | Preview the prune set; don't delete. |
--json | Machine-readable envelope. |
--md | Write a Markdown report. |
Pruning removes run blobs from state/runs/; it does not touch the snapshot cache.
dashboard
Launch the stepbook UI (a Vite dev server).
stepbook dashboard
stepbook dashboard -p 7000 --no-open
stepbook dashboard --host 127.0.0.1 --workspace ..| Option | Description |
|---|---|
-p, --port <n> | Port (default 6125). Strict — refuses to fall back if taken. |
--no-open | Don't auto-open the browser. |
-w, --workspace <path> | Workspace root for project discovery (default: parent of config dir). |
--host <addr> | Bind address (default 127.0.0.1; LAN access needs an explicit IP, not 0.0.0.0). |
Port behavior
stepbook dashboard -p <n> is strict: if the port is taken it errors, because you asked for a specific port. By contrast, npm run dev (the contributor entry point) falls through to the next free port.