Reticle Docs: verification for AI coding agents

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.

npx reticle <login|logout|whoami|link|project|config|push|runs|regression|share>

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
`<repo>/.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

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:

{
  "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`

npx reticle link [--project <name|id>]

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`

npx reticle project ls
npx reticle project create "My App"
npx reticle project rename <projectId> "New name"
npx reticle project rm <projectId>

rename and rm work but are not in the usage block. Missing or malformed arguments exit 2.

`reticle config`

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.

npx reticle share <runId>

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

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

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle cloud commands

Where credentials live

The commands

`reticle logout`

`reticle whoami`

`reticle link`

`reticle project`

`reticle config`

`reticle push`

`reticle runs`

`reticle regression`

Exit codes

Worked example

​Where credentials live

​The commands

​reticle login

​reticle logout

​reticle whoami

​reticle link

​reticle project

​reticle config

​reticle push

​reticle runs

​reticle regression

​reticle share

​Exit codes

​Worked example

Where credentials live

The commands

`reticle login`

`reticle logout`

`reticle whoami`

`reticle link`

`reticle project`

`reticle config`

`reticle push`

`reticle runs`

`reticle regression`

`reticle share`

Exit codes

Worked example