> ## 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. # reticle cloud commands > Sign in, link a repository, and read runs and regressions from Reticle Cloud. Ten subcommands bind this repository to Reticle Cloud so runs and flows land on a dashboard. They dispatch before the local parser, so `reticle login` is one tool, not a second binary. ```bash theme={"dark"} npx reticle ``` These are thin clients over the `/v1` API. The moat is the server, not the verbs. ## Where credentials live | Path | Contents | Secret | | ----------------------------- | ----------------------------------------------------------------------- | ------------- | | `~/.reticle/session.json` | `{ url, token, orgName }` from `reticle login` | Yes | | `~/.reticle/credentials.json` | Project-scoped API keys from `reticle link`, keyed by `projectId` | Yes | | `/.reticle/cloud.json` | `{ projectId, projectName, url, sync, verify }`. The non-secret binding | No, commit it | Auth for any command is `RETICLE_CLOUD_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`. ## The commands ### `reticle login` ```bash theme={"dark"} npx reticle login # browser device flow (the default) npx reticle login --email you@acme.com # headless: requests a code npx reticle login --email you@acme.com --code 123456 # headless: exchanges it npx reticle login --email you@acme.com --org "Acme" # --org is consulted only for a brand new account ``` With no `--email`, it runs a browser device flow like `gh auth login`: fetch a device and user code, open the browser to approve, poll until confirmed. With `--email` it keeps the two-step code path for CI and servers, because it proves you own the inbox before handing out a session. A local cloud whose dev mailer cannot deliver echoes the code back and completes in one command. ### `reticle logout` Empties `session.json`. Per-project keys in `credentials.json` stay. Prints `{ "loggedOut": true }`. ### `reticle whoami` The one call to make when you do not know your state. Real capture: ```json theme={"dark"} { "loggedInAs": "acme", "repo": { "attached": false, "projectId": null, "url": null, "sync": { "runs": true, "memory": true, "flows": true }, "verify": "local" } } ``` An unattached repo also gets a next-step nudge on stderr, telling you to run `reticle link`. ### `reticle link` ```bash theme={"dark"} npx reticle link [--project ] ``` Binds this repository to a cloud project. With a login token it **mints** a project-scoped key, so there is nothing to paste. With `RETICLE_CLOUD_KEY` already set, it resolves that key's project instead. `--project` accepts a slug id or a display name; omitted, it uses the `default` project. Writes `cloud.json` and the key. ### `reticle project` ```bash theme={"dark"} npx reticle project ls npx reticle project create "My App" npx reticle project rename "New name" npx reticle project rm ``` `rename` and `rm` work but are not in the usage block. Missing or malformed arguments exit `2`. ### `reticle config` ```bash theme={"dark"} npx reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server] ``` Edits `.reticle/cloud.json` in place. Any value other than `on` or `off` (or `local` or `server` for `--verify`) exits `2`. Requires the repo to be linked. ### `reticle push` Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. Prints `{ pushed, failed, total, project }`. ### `reticle runs` The linked project's recent run artifacts. The key scopes the query server-side. ### `reticle regression` The CI gate: which flows broke relative to before. **Exits `3`** when any flow regressed, which is the whole point of it being a separate command. ### `reticle share` ```bash theme={"dark"} npx reticle share ``` Mints a public proof link for one run. A missing `runId` exits `2`. ## Exit codes | Code | Meaning | | ---- | ----------------------------------------------------------------------------------- | | `0` | Success | | `1` | The API call failed, or the repository is not attached where attachment is required | | `2` | Usage error, or not signed in and no `RETICLE_CLOUD_KEY` | | `3` | `regression` only: at least one flow broke | Output is pretty-printed JSON on stdout. Errors and next-step nudges go to stderr, so an agent parsing stdout is unaffected. ## Worked example ```bash theme={"dark"} npx reticle login npx reticle project create "Checkout" npx reticle link --project "Checkout" npx reticle verify http://localhost:4173 # runs auto-push once linked npx reticle regression # exit 3 fails the pipeline ```