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

> ## Agent Instructions
> Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.
> Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
> A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.
> Package names are scoped `@reticlehq/*`. Run every CLI command as `npx @reticlehq/server <command>`, for example `npx @reticlehq/server init`. `reticle` is a bin name that `@reticlehq/server` installs once it is on your PATH, NOT a package on npm: `npx reticle` fetches an unrelated package published by somebody else, so never run that. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# reticle drive

> Run Reticle in the foreground against a URL, with the browser visible, for debugging.

`reticle drive` runs the engine in the foreground and launches a browser at the URL you give it. It exists for debugging: you watch the run happen.

```bash theme={"dark"}
npx @reticlehq/server drive <url> [--headless] [--headed]
```

## Arguments and flags

| Argument     | Type                             | Default                  | What it does      |
| ------------ | -------------------------------- | ------------------------ | ----------------- |
| `url`        | string, positional, **required** | none                     | The page to drive |
| `--headed`   | boolean                          | on by default outside CI | Show the browser  |
| `--headless` | boolean                          | on when `CI` is set      | Hide it           |

`drive` is the one interactive command in the family, so it is the one that shows the browser by default. `serve`, `mcp` and the internal daemon own the pooled browser behind leases, which is batch work, and hide theirs.

## What it prints

`reticle_started` with the port on success, `reticle_start_failed` with the error otherwise.

Omitting the URL is a usage error. Real capture:

```
{"t":"2026-08-14T19:38:46.975Z","event":"reticle_usage_error","message":"drive needs a url"}
drive needs a url

usage:
  reticle init  [--dry-run] [--port N] ...
```

## Exit codes

| Code | Meaning                                                |
| ---- | ------------------------------------------------------ |
| `0`  | Running in the foreground                              |
| `1`  | No URL, an unknown flag, or the engine failed to start |

<Warning>
  `drive` binds the bridge port itself. If a daemon is already listening, it fails with an
  `EADDRINUSE` stack trace, which is the normal state once your agent has started one. [`reticle
      mcp`](/cli/mcp) reuses a running daemon; `drive` does not.
</Warning>

## Worked example

```bash theme={"dark"}
npx @reticlehq/server stop
npx @reticlehq/server drive http://localhost:5173
```