@stepbook/cli

The stepbook command — the main way to drive stepbook, Storybook for typed pipelines, especially LLM ones. Run your pipeline, inspect every step's output, fix one step without re-running the rest, and measure drift over time — locally, in your repo.

Quickstart

Scaffold with npx (no install needed), then add stepbook to the project. The sample step imports @stepbook/runner and zod, so install all three:

mkdir my-pipeline && cd my-pipeline
npx @stepbook/cli init              # scaffold config + a sample step + sample input
npm install -D @stepbook/cli @stepbook/runner zod

Then drive the loop through the local binary with npx stepbook:

npx stepbook run         # execute the pipeline
npx stepbook check       # run assertions on the last run
npx stepbook dashboard   # open the inspector UI

Prefer a global stepbook command? npm install -g @stepbook/cli also works.

Commands

| Command | What it does | | --- | --- | | stepbook init | Scaffold a new project. | | stepbook add-step <name> --type <type> | Add a step file. | | stepbook run [input] | Execute the pipeline (--from, --to, --just, --no-cache, …). | | stepbook check | Run assertions on the last run without re-executing. | | stepbook diff | Compare two whole runs (--from/--to selectors); assertion flips + drift summary. | | stepbook snapshot-diff <step> | Compare a single step's output between two runs. | | stepbook variance <step> | Stability/drift report over N runs. | | stepbook q <step> <query> | Query historical runs (JSONata / StepQL). | | stepbook dashboard | Open the inspector UI. |

Every command supports --json for a versioned, machine-readable envelope ({ ok, command, version, data }) with stable exit codes — so AI coding agents can drive it as a tool, not just humans.

Docs

• CLI reference
• Agent contract
• Guide & concepts

License

MIT