The CLI’s job is to spin up a sandbox — for local dev and as the operator entry point. It is not
the primary control surface for tests; that’s the SDK.
prod-break run <pack>
Boot one sandbox instance. Prints its URL and instance-minted key.
npx prod-break run stripe
# ▸ sandbox ready url=http://localhost:8801 key=pbw_3f9a… pack=stripe@0.1.0
| Flag | Description |
|---|
--workers N | Boot N instances for parallel test workers; print N url/key pairs and export PRODBREAK_WORKER_URLS / PRODBREAK_WORKER_KEYS (ordered CSV). Guide |
--port <p> | Bind the (first) instance to a specific port instead of an auto-chosen one. |
--key <k> | Pin the instance key (reproducible CI) instead of minting a fresh one. |
--t0 <iso> | Set the world’s canonical start time. |
Environment contract
Plugins read these so you don’t pass URLs around by hand:
| Variable | Set by | Read by |
|---|
PRODBREAK_URL / PRODBREAK_KEY | single-instance run | plugins (single-worker) |
PRODBREAK_WORKER_URLS / PRODBREAK_WORKER_KEYS | run --workers N | plugins (per worker) |
seed / reset may arrive as CLI subcommands later for shell convenience, but the SDK is the
intended control path for tests. The CLI owns instance lifecycle (provisioning, eviction of stuck
workers).