> ## 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/*` and the CLI is `reticle`. Install with `npx reticle init`. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version. # CLI reference > Every reticle command. What it does, what it prints, and what it exits with. Captured from real runs. The CLI is mostly for you, not your agent. Your agent talks MCP; you use these to set things up, work out why nothing connected, and wire verification into CI. ```bash theme={"dark"} npx @reticlehq/server ``` Every output block on this page was captured by running the command. Where an exit code is quoted, it was measured, not assumed. ## Setup and diagnosis ### `reticle init` Wires Reticle into the project in the current directory. ``` reticle init [--dry-run] [--port N] [--no-mcp] [--no-install] [--app ] ``` What it writes, and how to read its four status marks. ### `reticle doctor` The first thing to run when something is wrong. One command, the whole setup. ```bash theme={"dark"} npx reticle doctor ``` ``` reticle doctor node v22.14.0 chromium ✓ installed daemon ✓ running on :4400 (pid 24735, v2.7.0) bridge port 4400 (your app must dial THIS port — not your dev-server port) daemon log /Users/you/.reticle/daemon-4400.log tracing RETICLE_TRACE=1 on the daemon for per-stage timings in that log ``` Exits `0`. That parenthetical about the bridge port is doing a lot of work. Mixing it up with the dev-server port is the most common setup failure there is. ### `reticle status` Whether the daemon is up and which apps have connected. ```json theme={"dark"} { "event": "reticle_status", "port": 4400, "running": true, "pid": 24735, "sessionCount": 1, "sessions": [ { "sessionId": "sece96901…", "url": "http://localhost:4312/", "throttled": true, "stale": false } ] } ``` Exits `0`. A session in the list is the install genuinely finished. Not a tick in a checklist, a connected app. ### `reticle telemetry [status|enable|disable]` ```bash theme={"dark"} npx reticle telemetry status ``` ``` telemetry disabled (this is a Reticle source checkout — developing it is not using it) policy https://github.com/reticlehq/reticle/blob/main/docs/telemetry.md ``` The complete list, and how to turn it off. ## Running the app | Command | What it does | | --------------------- | ----------------------------------------------------------------------------------- | | `reticle serve` | Start the daemon in the foreground. `--drive `, `--headless`, `--http` | | `reticle stop` | Stop it | | `reticle open [url]` | Show the app. Reuse the connected tab, or open one | | `reticle drive ` | Foreground mode, for debugging | | `reticle mcp` | The MCP stdio proxy. Auto-starts the daemon if needed. This is what your agent runs | `reticle drive` will fail with an `EADDRINUSE` stack trace if a daemon is already listening on the port. Which is the normal state once your agent has started one. `reticle mcp` reuses a running daemon; `drive` currently does not. ## Verification ### `reticle verify ` One-shot: drive the URL, replay the saved flows, exit `0` on pass. This is the command for CI when you do not want a model in the loop. ```bash theme={"dark"} npx reticle verify http://localhost:5173 --timeout 60000 ``` Options: `--headed`, `--timeout N`, `--storage-state `. That last one is how you verify flows behind a login without scripting the login every time. ### `reticle affected` Which saved flows must re-verify for a set of changed files. ```bash theme={"dark"} npx reticle affected --since HEAD~1 ``` ```json theme={"dark"} { "event": "reticle_affected", "changedFiles": ["docs/README.md", "packages/server/src/tools/docs-index-coverage.test.ts"], "affected": ["deploy-journey", "verify-modal", "verify-route", "…"], "unknownProvenance": ["deploy-journey", "verify-modal", "…"] } ``` `unknownProvenance` lists flows Reticle could not map to source files, so it includes them to be safe. A flow recorded before provenance tracking existed has no file list, and Reticle would rather re-run it than skip it and miss a regression. A large `unknownProvenance` means your flows predate the feature. Re-record the ones you care about to get precise selection. ### `reticle gate` The CI gate. Exits non-zero unless passing artifacts cover the affected flows. ```bash theme={"dark"} npx reticle gate --since HEAD~1 ``` ```json theme={"dark"} { "event": "reticle_gate", "pass": false, "uncovered": ["deploy-journey", "verify-modal", "…"], "quarantined": ["drift-demo", "qa2-flow"], "coverage": { "pct": 9, "covered": 4, "total": 47 } } ``` Measured exit code: **`1`**. That run genuinely failed, with 4 of 47 flows covered, which is what a gate is supposed to do when you have not verified anything yet. `quarantined` flows are excluded from the pass/fail decision. Quarantine is for a flow that is known flaky and being fixed; it is not a place to hide failures, because the list is printed on every run. ### `reticle watch [url]` On save, report which saved flows must re-verify. The interactive companion to `affected`. ## Maintenance | Command | What it does | | ------------------ | --------------------------------------------------- | | `reticle update` | Install the latest server version and restart | | `reticle rollback` | Restore the previous version and restart | | `reticle license` | Enterprise license status: active, eval, or missing | | `reticle version` | Print the version | | `reticle help` | Usage for everything | `rollback` exists because an auto-updating dev tool that cannot go back is a dev tool that can ruin your afternoon. It restores the previous version and restarts in one step. ## Feedback ```bash theme={"dark"} # humans npx reticle feedback "what worked, what didn't" # agents, including from a setup that never finished npx reticle feedback --agent --kind "what happened" ``` The `--agent` form matters more than it looks: the setup that failed halfway is exactly the setup worth hearing about, and in that state the MCP tools do not exist yet. What each kind means, and what happens when a report cannot be delivered. ## `reticle identify` Opt-in, and off by default: ```bash theme={"dark"} npx reticle identify --context company|side_project|open_source|learning [--email E] [--forget] ``` Only useful if you want support or an enterprise trial. `--forget` removes it.