> ## 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 status

> Ask whether the Reticle daemon is up and which app sessions have connected to it.

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

```bash theme={"dark"}
npx reticle status [--port N]
```

## Flags

| Flag       | Type   | Default                                                    | What it does        |
| ---------- | ------ | ---------------------------------------------------------- | ------------------- |
| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which daemon to ask |

## What it prints

One JSON line on stdout. Real capture, daemon up and no app connected:

```json theme={"dark"}
{
  "t": "2026-08-14T19:38:37.737Z",
  "event": "reticle_status",
  "port": 4400,
  "running": true,
  "pid": 4795,
  "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 ... (2) There is no `.reticle.json` in the directory this daemon is running in ..."
}
```

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

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

## Exit codes

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

## Worked example

```bash theme={"dark"}
npx reticle init
npx reticle status    # a session in the list means the app is genuinely wired
```

<Card title="Nothing connected?" icon="triangle-exclamation" href="/troubleshooting">
  The bridge port is not your dev server port, and that is the most common cause.
</Card>