Reticle Docs: verification for AI coding agents

reticle status is the command that tells you whether the install actually finished. Not a tick in a checklist: a connected app.

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

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   enumerated

And with no daemon on the port:

reticle status
  daemon       ✗ not running on :4999
  agent link   never-attached
  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 event line on stderr, for a caller that parses rather than reads:

{
  "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,
  "stale": false,
  "pendingMarks": 0
}

Field	Meaning
`running`	Whether a usable daemon owns the port
`presence`	Present when the pid file is dead: `daemon`, `foreign`, or `absent`. The port is asked, not just the pid file
`pid`	The daemon process
`sessionCount` / `sessions`	Connected app sessions, each with `sessionId`, `url`, `throttled`, `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