> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firedrill.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run a complete local drill and inspect its evidence.

This guide runs a small, deterministic agent against one synthetic Tool. You will validate the repository source, execute a passing drill, and open a self-contained report.

## Prerequisites

* Node.js 20.19 or later
* pnpm 9.15 through 10
* Git

<Info>
  Public package installation is not available yet. These steps build the current release candidate from source, which currently requires repository access. Once the repository and packages are public, the normal path will be `npm install --save-dev @firedrill/cli` and `npx firedrill init`.
</Info>

<Steps>
  <Step title="Build the release candidate">
    ```bash theme={null}
    git clone https://github.com/firedrill-tools/firedrill.git
    cd firedrill
    pnpm install --frozen-lockfile
    pnpm build
    export FIREDRILL_CLI="$PWD/packages/cli/dist/bin.js"
    firedrill() { node "$FIREDRILL_CLI" "$@"; }
    ```

    The shell function keeps the built CLI available while you work through this guide.
  </Step>

  <Step title="Create a runnable example">
    From the Firedrill checkout:

    ```bash theme={null}
    mkdir ../my-first-drill
    cd ../my-first-drill
    firedrill init --path template
    ```

    The template creates a Tool, baseline data, one target, and one drill. Generated runtime data and reports go under `.firedrill/`, which the initializer adds to `.gitignore`.
  </Step>

  <Step title="Check what will run">
    ```bash theme={null}
    firedrill validate
    firedrill plan
    ```

    `validate` checks the source without writing a build. `plan` shows the semantic world that Firedrill would compile.
  </Step>

  <Step title="Run the drill">
    ```bash theme={null}
    firedrill run changes-resource
    ```

    Firedrill creates an isolated SQLite-backed world, starts the Tool interfaces, invokes the example target, evaluates the assertions, and writes terminal, JSON, JSONL, JUnit, and HTML results.
  </Step>

  <Step title="Open the results">
    ```bash theme={null}
    firedrill inspect
    ```

    Use the inspector to move between Tools, starting data, drill definitions, runs, assertions, state changes, and attachments. You can also open `.firedrill/reports/index.html` directly for a static report index that needs no server.
  </Step>
</Steps>

## Read the project

```text theme={null}
my-first-drill/
├── .gitignore
├── firedrill.json
├── firedrill-example/
│   └── agent.mjs
├── firedrill/
│   ├── README.md
│   ├── world.yaml
│   ├── tools/
│   │   └── resource-store/
│   │       ├── resource-store.tool.yaml
│   │       └── behavior.mjs
│   ├── scenarios/
│   │   └── baseline.scenario.yaml
│   ├── targets/
│   │   └── starter-agent.target.yaml
│   ├── drills/
│   │   └── changes-resource.drill.yaml
│   └── suites/
│       └── resource-store-conformance.suite.yaml
└── .firedrill/                  # generated and ignored
```

The files under `firedrill/` describe the controlled environment and its tests. The agent remains separate. YAML, YML, and JSON resource files are supported, and Firedrill discovers them recursively beneath the configured source root.

## Connect your own agent

Replace the example target with one boundary your agent already exposes:

| Agent boundary                       | Firedrill target or adapter           |
| ------------------------------------ | ------------------------------------- |
| Executable or script                 | Command target                        |
| Local service                        | HTTP target                           |
| JavaScript or TypeScript entry point | Module target                         |
| Test-runner callback                 | External target through `runDrills()` |

Then map the synthetic Tool connection into the configuration that your agent already reads. Firedrill supports direct, HTTP, MCP, and spawned CLI Tool bindings.

<Warning>
  Firedrill cannot transparently intercept every hardcoded dependency. Keep production logic unchanged, but provide a configurable endpoint, client factory, module mock, or another test-side seam.
</Warning>

## Make the result fail on purpose

Open `firedrill/drills/changes-resource.drill.yaml`. Change only one assertion's expected value while leaving the task input unchanged, then rerun:

```bash theme={null}
firedrill run changes-resource
```

The command exits with code `1`, and the report shows expected and actual values together. Restore the assertion when you finish reviewing the failure.

## Next steps

<CardGroup cols={2}>
  <Card title="Connect an existing agent" icon="link" href="/guides/connect-agent">
    Choose the correct target and Tool-binding seam.
  </Card>

  <Card title="Build a Tool" icon="wrench" href="/guides/create-tool-package">
    Define operations, state, behavior, faults, events, and an optional UI.
  </Card>

  <Card title="Use your test runner" icon="flask" href="/sdk/local-typescript">
    Call `runDrills()` from Jest, Vitest, Mocha, or application tests.
  </Card>

  <Card title="Understand reports" icon="timeline" href="/guides/results">
    Read verdicts, causal evidence, state differences, and reproduction data.
  </Card>
</CardGroup>