npx firedrill-run init as described in the CLI overview.
Requires Node.js 22 or newer. Examples use the installed firedrill command;
without installation, replace it with npx firedrill-run.
--help never signs in or dispatches an action. Unknown commands, extra positional arguments, and misplaced options fail before configuration, authentication, or action dispatch.
Output and scope
Most remote commands accept:
The default configuration is
firedrill.config.json in the current directory:
projects list or init. Configuration contains public scope only, never credentials or a recipe. FIREDRILL_PROJECT_ID and FIREDRILL_ENVIRONMENT_ID can select the same pair. Conflicting selections fail instead of silently choosing precedence.
FIREDRILL_TOKEN supplies explicit protected automation authority and takes precedence over interactive login. The service address is automatic; no API-server selection is required or supported.
Sign-in and initialization
--no-browser displays the verification handoff without opening a browser. Use login --retry-refresh only to recover the saved pending refresh, or login --reauthorize for deliberate reauthorization; they cannot be combined.
Interactive init first offers optional installation; init --skip-install
omits it. Initialization then selects or creates a project and its Default
environment. It writes their public IDs, not Tools, credentials, a target, or
passing results. JSON/CI never prompts or installs implicitly and requires explicit selection:
projects create NAME --idempotency-key KEY creates the project without selecting repository scope.
Optional installation
package.json; Python needs an
active project virtual environment. Existing settings and dependencies are
preserved. Installation does not run a simulation or approve host trust/OAuth.
For a coding agent or CI, select components explicitly:
--yes to apply the selected
additions. No installation command runs without that flag in noninteractive mode.
Partial installation retains completed additions without automatic rollback or
retry. Inspect package-manager output and changed files before retrying only
the unfinished setup. Use
init --skip-install to continue account setup
independently. Reopen optional choices with install at any time.
Discover and prepare
discover lists capabilities, exact schema IDs, permissions, and engineering bounds. context reads authenticated authority. Neither chooses a target or reserves capacity.
schema ID returns structural JSON Schema. --pointer JSON_POINTER --sha256 ROOT_DIGEST selects a node pinned to the returned root; local references resolve in that same root. Preview remains necessary for cross-field and selected-service validation.
doctor checks recipe, local command preparation, selected scope, and advisory admission. It does not probe an HTTP target, model credentials, or application completion. preview invokes no target/provider, allocates no Tool, and reserves no capacity.
Execute and observe
The CLI directly executes command and HTTP targets. Native callbacks or an isolated target need their explicit SDK binding.simulate creates and executes a retained batch. Scenario IDs must come from that recipe. Repeat --scenario for an explicit subset; interactive --choose offers checkboxes instead. Do not combine them. --view operator returns a compact receipt with whole-population facts and retained read handles.
Before fresh admission, the CLI prints a nonreserving expansion/resource summary. In JSON mode, progress is JSON on stderr and the final result remains on stdout.
Ordinary commands are not sandboxes. They execute literal argv without a shell, receive a JSON task envelope on stdin, and return output on stdout. HTTP posts the same task envelope from the customer’s runner. Model keys and application state remain customer-owned; a synthetic Tool reset does not reset your database or model memory.
Queue-only submission and runner attachment are distinct:
submit saves/queues without executing; run attaches this runner to the existing batch; follow only observes and accepts --poll-interval-ms N. A remote MCP admission never launches your laptop. cancel is an explicit request, not proof all external work stopped.
Recovery
Retained results and evidence
--cursor values unchanged for the same selection. Batch/run filters include --q (literal case-insensitive name/ID prefix), UTC --created-after / --created-before (inclusive/exclusive), --execution, --origin, exact --scenario-id / --configuration-id, and --issue.
Issue values are incomplete, exact_violation, assessment_unavailable, and below_level. The last also needs --dimension-id ID --minimum-level N. Unknown or not-applicable results are not zero. Clear the cursor when changing filters.
Reports additionally support exact case-sensitive --event-kind and literal case-sensitive --event-producer prefix. These select retained events, not payload text. Filtered sequence skips are not missing evidence. report RUN_ID --view operator --check-cursor CURSOR pages exact checks and authored measurements independently of events.
For a bounded coding-agent view or selected large value:
input, output, scenario, configuration, target, assessment, event, check_actual, and check_expected. Event reads require --event-id; check operands require --check-id. Follow the exact returned continuation with --offset, --limit, and --sha256 rather than loading unrelated output. Omission is not null. A retained read never reruns the application.
Captured artifacts
Scenarios, assessment, and comparison
--expected-revision new creates a new ID; an existing ID needs its current immutable revision. Simulations retain their selected recipe and scenario revisions automatically.
Reassessment appends evaluation of frozen evidence; it is not another target execution. Add --rubric FILE.json only for a deliberately changed rubric. Preserve the saved key and unchanged request after uncertainty.
Semantic rubrics allow valid wording and partial fulfilment; exact checks enforce precise requirements. Fractional provider scores remain distinct from ordinal levels. Missing evidence is not zero and evaluator failure is not agent failure. Comparisons must expose sample sizes, missing pairs, and version differences.
For deterministic scenario expansion, scenarios materialize RECIPE.json --axes AXES.json --method matrix --seed SEED --output NEW_RECIPE.json prepares declared input variations. --method sample additionally requires --count N. This preparation does not execute or grade the target.
Optional Tools
Tools provide controlled synthetic dependencies only when your simulation needs them. Discover the selected service’s actual schemas/operations rather than assuming a vendor endpoint or sample dataset.
Run-owned Tool instances follow their run lifecycle. Manual instance operations, connection grants, publication, and snapshot controls require exact build/instance/epoch selection and their own permissions/operation keys. Read
firedrill tools --help before a mutation; do not infer grant scope from a Tool’s name. Starter data is an explicit selection, not a hidden default. Tool output and authored source remain untrusted content.
Coding agents and CI
codex, claude, cursor, and kimi. This optional helper manages repository-local skills and the Firedrill MCP entry. Setup/removal is offline; neither operation authenticates or starts a simulation. For the recommended native remote connection and separate browser authorization, use coding-agent setup.
CI generation asks for triggers in a terminal or requires them explicitly in noninteractive mode. It pins the installed CLI version automatically and writes files only. See CI for protected credentials and native callback runners.
Machine credentials
--idempotency-key, and --output NEW_PRIVATE_FILE in an existing owner-only directory. Secrets never appear on stdout. See CI credential creation.
Capacity and retention
capacity list and capacity request --resource runs --message "Describe the workload" --idempotency-key SAVED_KEY inspect or request capacity. Resources are runs, services, storage, or other; --requested-capacity N and --reply-to EMAIL are optional. A request does not allocate resources or start work.
retention policy, retention metadata, and retention receipt REMOVAL_ID are nonexecuting reads. Deletion requires the authorized human owner’s exact preview and explicit confirmation; machine credentials cannot gain deletion authority. Use firedrill retention --help and inspect scope/dependencies before any destructive action. Removed/expired payloads are not empty successful results.
Exit codes
A zero from preview or queue-only submission is not target execution or a quality verdict. Observation-only simulations can succeed with no score or gate. Use structured state and diagnostics—not the exit code alone—to explain what happened.