Skip to main content
Running drills takes four commands: plan reviews the world, apply prepares it and creates a campaign, run starts your agent on your machine, and watch follows progress.

1. Review the plan

The plan review shows:
  • The world revision and the number of drills.
  • Whether drills run one at a time.
  • The synthetic tools that will be prepared.
  • Any unresolved requirements, in plain language.
  • The credit estimate.
A plan review changes nothing, starts nothing and spends no credits. It expires after a while. If it expires, run plan again. To see an existing review, run firedrill plan show <plan-id>. Fix every unresolved requirement before you apply. See Worlds.

2. Apply the plan

A person should read the plan review before this step.
apply reserves the estimated credits, prepares the synthetic tools and creates a campaign. The campaign’s drills are allocated but not started. The command prints the campaign ID and the run command to use next. With --follow, the command waits until preparation is ready, failed or cancelled. If it is interrupted, check it with the request key it printed:
If your organization asks for an extra budget confirmation, add --approve-credits.

3. Enroll your machine

This registers your machine as a runner and stores its key in your operating system’s credential store. You need to do this once per sign-in. Runners need macOS or Linux on arm64 or x64. Enrolling a machine does not give it permission to run anything. Each run still asks you.

4. Run the drills

run checks that the plan matches the descriptor, then prints the plan review: each root folder, each service in start order, its command, the environment variable names and the driver. It asks you to approve. Then it starts your services, runs the drills and stops the services when they finish. Keep the terminal open until it prints Companion stopped with the number of completed and failed drills. Press Ctrl-C to stop early. Either --plan or --descriptor can be - to read from stdin, but not both.

Without a stored sign-in

If you signed in with firedrill init --session-only, the CLI keeps your sign-in in memory in that terminal. run can then enroll a temporary runner for this session after you agree, or when you pass --enroll-device. This only works when every service in the plan is per_drill.

5. Watch progress

watch shows the campaign state and one line per drill. With --follow, it updates until the campaign settles. You can also follow the campaign in the web app under Simulations.

Cancel a campaign

Only the person who created the campaign can cancel it. Follow the cancellation with firedrill watch <campaign-id> --follow.

Drill states

Read reports

Endings, results and evidence.

Agent mode

Run these commands from a coding agent.