Reticle Docs: verification for AI coding agents

reticle status tells you whether the daemon is up and which pages connected, who you are signed in to Reticle Cloud as, and whether this folder is linked to a cloud project. The account facts come from local files; no network call is made. A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.

npx @reticlehq/server status [--port N] [--json]

Flags

Flag	Type	Default	What it does
`--port N`	number	`4400` (or `RETICLE_PORT`, or the port in `.reticle.json`)	Which daemon to ask
`--json`	flag	off	Print the machine-readable event instead of the block below

What it prints

The block also carries an account row: who you are signed in as and the cloud project this folder is linked to, or what to run (reticle connect) when it is not. reticle whoami is the old name for this question; it still works for one release.

  account      ✓ signed in as Acme
               this repo is not linked: run `reticle connect`

A short block, for whoever is reading the terminal. Real capture, daemon up with two apps connected:

reticle status
  daemon       ✓ running on :4400 (pid 90790)
  sessions     ✓ 2 pages connected
               http://localhost:5173/  (throttled, hidden)
               http://localhost:7699/  (throttled, hidden)
  agent link   ✓ your agent has read and used Reticle's tools
  agents       Connected: Claude Code ✓
               Cursor not connected yet: restart Cursor, then turn Reticle on in Settings › MCP

The agents row has one line for each coding agent on this machine. A line shows ✓ when that agent connected to Reticle at least one time. Otherwise it shows the step that is still missing. reticle setup mcp prints the same lines. And with no daemon on the port:

reticle status
  daemon       ✗ not running on :4999
               port presence: free
  agent link   no agent has started Reticle on this port yet
               no MCP client has started Reticle on this port, so either the server is not
               registered with your client or nothing has attached since this record began:
               register it with `npx @reticlehq/server init`, then restart your MCP client and
               run status again.
  next         no daemon is running on this port, which is normal. An agent starts it when it
               first calls a Reticle tool, and it exits again when idle. Ask your agent to verify
               something, then run status again.

A session’s parenthesised notes are the ones that explain an answer you would otherwise call a bug: throttled and hidden mean a background tab answering slowly, stale means the page has moved on from what the daemon last saw, and unresponsive means it is not answering at all.

`--json`

The same facts as one JSON line on stdout, so a caller can pipe it to a parser:

npx @reticlehq/server status --json | jq '.running, .sessionCount'

{
  "t": "2026-08-15T18:43:33.724Z",
  "event": "reticle_status",
  "port": 4499,
  "running": true,
  "pid": 78137,
  "sessionCount": 0,
  "sessions": [],
  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans (3000, 3001, 4200, 4321, 5000, 5173, 5174, 8000, 8080, 8100, 9000, 1420, 3100, 4173, 5175, 7860, 8501), so the dev server may not be running ... (2) There is no `.reticle.json` in the directory this daemon is running in ..."
}

It is one line in the terminal, pretty-printed here, with why trimmed at the ellipses. With an app connected why is absent and each session carries its own fields:

{
  "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
  "url": "http://localhost:4310/",
  "throttled": false,
  "hidden": false,
  "stale": false,
  "pendingMarks": 0
}

Field	Meaning
`running`	Whether a usable daemon owns the port
`presence`	Present when no usable daemon answered: `foreign` (something else holds the port) or `free`. The port is asked, not just the pid file
`pid`	The daemon process
`sessionCount` / `sessions`	Connected app sessions, each with `sessionId`, `url`, `throttled`, `hidden`, `stale`, `pendingMarks`
`why`	Present when zero sessions connected. Names the two likely causes and refuses to assert either
`updateAvailable`	Present when a newer server version is on the registry

status asks the port, not only the pid file. running: false used to be printed about a port that was demonstrably occupied, which sent the reader off to start a daemon that could never bind.

Exit codes

Always 0. This command answers a question; it does not judge the answer.

Worked example

npx @reticlehq/server init
npx @reticlehq/server status    # a session in the list means the app is genuinely wired

Nothing connected?

The bridge port is not your dev server port, and that is the most common cause.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle status

Flags

What it prints

`--json`

Exit codes

Worked example

Nothing connected?

​Flags

​What it prints

​--json

​Exit codes

​Worked example

Nothing connected?

Flags

What it prints

`--json`

Exit codes

Worked example