Skip to main content
The CLI runs simulations from your application repository. Your application and model credentials stay in your execution environment; Firedrill coordinates runs and retains their evidence.

​
Start in your repository

Requires Node.js 22 or newer.
Run init from your application repository. Its optional wizard offers project or global CLI installation, MCP configuration, skills, and an SDK. Use arrow keys for one choice, Space to toggle checkboxes, and Enter to continue. Review the exact changes before applying; skip anything you do not need. Setup then offers browser sign-in and selects or creates a project with its Default environment. It saves public IDs in firedrill.config.json, not credentials. It does not select Tools, run your application, or upload your repository. MCP browser authorization remains separate. npx firedrill-run offers setup on its first interactive launch in a repository. Later bare launches show a compact welcome. Use npx firedrill-run install to reopen the choices, or npx firedrill-run init --skip-install for account/project setup only. JSON and CI modes never prompt or install implicitly. Use the same prefix for another command:
For repeated use, install the CLI globally once:
The examples below use the installed firedrill command. Without a global installation, replace firedrill with npx firedrill-run.
Or choose In this project in the wizard. Keep using npx firedrill-run; bare npx firedrill is not the fresh installer and can resolve an unrelated package.
The service address is selected automatically. You do not configure an API server.

​
Let your coding agent prepare the simulation

For Codex, use its native MCP and plugin commands:
These are user-wide in Codex. Coding-agent setup provides the native Claude Code commands and Cursor/Kimi paths. MCP browser authorization is separate from this CLI’s sign-in. Use the same intended organization; do not copy credentials between clients. Adding the server or plugin does not start an agent or approve host trust. Ask your coding agent to inspect your application’s existing command, HTTP endpoint, or callable; define a small scenario set; and explain the execution and reset boundary before running it. Tools and evaluation are optional.

​
Run an existing recipe

With a recipe prepared for your actual application:
In a terminal, choose the recipe with arrow keys and Enter. Add --choose to select scenarios using Space. Discovery reads valid recipe JSON in the current directory and firedrill/; it does not invent a recipe or run a target to find one. An exact path also works: firedrill simulate firedrill/scenario.json. simulate creates a retained batch and runs command or HTTP targets from this machine. For preparation without execution, use firedrill doctor or firedrill preview. Native callbacks use the TypeScript or Python SDK. The result includes batch/run IDs, a recovery operation ID, and an authenticated report link. Use returned IDs—not the labels below:
Execution, observed output, assessment, and an optional CI gate are separate. An observation-only simulation is valid; completion does not imply task success or a passing score.

​
Automation and recovery

Use --json --non-interactive for scripts. These modes never open menus or a browser and never install implicitly. Explicit install selections return a read-only plan until --yes is supplied; see optional installation. CI supplies a scoped FIREDRILL_TOKEN through its secret store; see CI.
If exactly one valid recipe is discovered, the filename can be omitted in automation too. With multiple candidates or incomplete discovery, provide the exact path; the CLI reports candidates rather than guessing. If execution is interrupted or a response is uncertain, preserve the private journal and the printed operation ID. Reconcile that execution with firedrill simulate --resume OPERATION_ID. Use follow BATCH_ID only to observe: it never dispatches target work. See the command reference for scope selection, queue-only submission, retained reads, and exit codes.