> ## 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/*`. Run every CLI command as `npx @reticlehq/server <command>`, for example `npx @reticlehq/server init`. `reticle` is a bin name that `@reticlehq/server` installs once it is on your PATH, NOT a package on npm: `npx reticle` fetches an unrelated package published by somebody else, so never run that. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# reticle restart

> Free the bridge port and put a daemon back on it, reporting each half separately.

`reticle restart` is [`reticle kill`](/cli/kill) followed by a daemon start that waits for a real bind.

```bash theme={"dark"}
npx @reticlehq/server restart [--port N] [--force]
```

## Flags

| Flag       | Type    | Default                                                    | What it does                                                           |
| ---------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `--port N` | number  | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which port to restart on                                               |
| `--force`  | boolean | `false`                                                    | Passed to the kill half: clear a listener that is not a Reticle daemon |

## The two halves are reported separately

A restart that killed the old daemon and then could not start a new one leaves you somewhere quite different from one that could not kill anything at all, and a single `ok: false` cannot tell you which happened. So each half prints its own line.

Real capture, restarting over a running daemon:

```
{"event":"reticle_killed","port":4499,"pid":84513,"escalated":false,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone — it goes dormant and starts a fresh daemon on the next tool call."}
{"event":"reticle_daemon_spawned","port":4499}
```

Real capture, when the port is held by something that is not ours:

```
{"event":"reticle_kill_refused","port":4498,"reason":"pid 84537 (\"Python\") is listening, and it is not a Reticle daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. Run it again with --force if that is what you meant, or start Reticle on another port.","holder":"Python"}
{"event":"reticle_restart_aborted","port":4498,"reason":"the port was not freed, so nothing was started — the old holder is still there"}
```

<Note>
  The start half is `serve`'s, which waits for the daemon to **answer** before claiming it started
  and exits non-zero when it does not. A restart never reports success for a daemon that never
  bound.
</Note>

## Exit codes

| Code | Meaning                                                   |
| ---- | --------------------------------------------------------- |
| `0`  | The port was freed and a daemon is answering on it        |
| `1`  | The port was not freed, or the new daemon did not come up |

## Worked example

```bash theme={"dark"}
npx @reticlehq/server restart         # after an upgrade, so the new version is the one serving
npx @reticlehq/server status
```

<Card title="Why not lsof" icon="skull" href="/cli/kill">
  The pipeline everyone reaches for kills the agent's own MCP proxy along with the daemon.
</Card>