# Command reference
`openlatch --help` is always current. This page adds what `--help` cannot: what each command guarantees, and how to read what it prints.
## Commands
| `openlatch init` (alias `setup`) | Complete, idempotent reinstall. Reclaims the ports first — identifying the holder **by the port**, not by `daemon.pid` — then proves the daemon it started is the one serving (PID, version, `/health`). |
| `openlatch status` | Dashboard plus the twelve-section verdict |
| `openlatch start [--foreground] [--port N] [--boundary-port N]` | Refuses when a daemon already runs (`OL-1501`, exit 5) |
| `openlatch stop` / `restart` | `stop` also removes the agent's boundary wiring, and says so |
| `openlatch doctor` | Full diagnosis with causes and remedies |
| `openlatch doctor --fix` | Heals what it can, backs up to `.bak` siblings + `~/.openlatch/fix-journal.json`. Never re-enables what you switched off. |
| `openlatch doctor --restore` | Reverses the last `--fix`. Surgical merge preserves your non-OpenLatch hooks. |
| `openlatch doctor --rescue [--since 24h] [--yes]` | Redacted diagnostic ZIP for support |
| `openlatch boundary status` | Full classification, not a port probe |
| `openlatch boundary {enable,disable} [-y] [--no-restart]` | Writes `[boundary] enabled`, then offers the restart that applies it |
| `openlatch hooks status` | The Hooks section in detail |
| `openlatch supervision {install,uninstall,enable,disable,status}` | OS-native supervisor (launchd / systemd --user / Task Scheduler), user-scope only |
| `openlatch inventory {list,log,rescan,status,inspect,projects,ack}` | Configuration-plane monitoring |
| `openlatch proxy {status,discover,set,clear,test}` | The egress route. See [egress.md](egress.md#commands). |
| `openlatch evaluate [--describe]` | Pure NDJSON evaluation from supplied inputs; no daemon or configuration required. See [the evaluation protocol](evaluate-protocol.md) for frames, state ownership and its command-specific exit codes. |
| `openlatch auth {login,logout,status}` · `openlatch telemetry {…}` · `openlatch update` · `openlatch logs` · `openlatch uninstall [--purge]` · `openlatch docs` | |
Noun-verb aliases: `hooks install` = `init`, `daemon start` = `start`, and so on — identical arguments, pinned by test.
Global flags: `--json`, `--verbose`/`-v`, `--debug`, `--quiet`/`-q`, `--no-color`. Every diagnostic's JSON carries the same `sections[]` the human rendering shows.
### `init` flags
`init` additionally takes the egress flags — highest precedence, applied per key:
| `--proxy <url>` | The proxy to use. **Never put a credential in it**: command-line arguments are readable by every process on the host (`/proc/<pid>/cmdline`, Win32 `CommandLine`), so a URL carrying `user:pass@` is rejected with `OL-1226`. Use `OPENLATCH_PROXY` or the prompt — both store the password in the OS credential store. |
| `--no-proxy <list>` · `--ca-bundle <path>` · `--proxy-mode <auto\|manual\|direct>` · `--proxy-auth <auto\|none\|basic\|negotiate>` · `--proxy-spn <spn>` | Persisted to `[proxy]`. |
| `--yes` | Never prompt, even on a terminal. An install that would have to ask a question fails instead, naming what it needed — the only way to script an install from an interactive shell. |
| `--dry-run` | Report what would happen to the egress route and exit. Writes no file and creates no directory, not even `~/.openlatch`. With `--json`: `proxy: { action: "keep"\|"discover"\|"persist", source? }`. |
## Reading a health report
Every command that reports health — `status`, `doctor`, `boundary status`, `hooks status`, `proxy test` — renders the same twelve sections from one model, so a state means the same thing wherever you see it.
### States
| `Ok` | `✓` | Enabled **and proven working**. The only green. |
| `Off` | `⚠` | Switched off deliberately. Always carries a code and a remedy. |
| `Degraded` / `Pending` | `⚠` | Working, but not at full capability, or still verifying |
| `Unknown` | `⚠` | Blocked by another section, which it names. One outage, one cross. |
| `Failed` | `✗` | Enabled and not working |
| `NotApplicable` | `·` | Absent from the build, an exercised privacy opt-out, or persistence inside a sandbox |
### Sections
Twelve sections, always all reported, under three groups — the questions a reader asks in the order they ask them:
| **Runtime** | Environment · Daemon · Persistence · Update | is it running, and will it keep running? |
| **Coverage** | Hooks · Boundary · Policy · Inventory · Integrity | is it seeing everything, and enforcing? |
| **Platform** | Connection · Cloud · Telemetry | is any of it leaving this machine? |
`Policy` sits under Coverage, not Platform: the bundle arrives from the cloud but the evaluation is local and authoritative — it is about what this host enforces, not about what leaves it.
`Connection` sits before `Cloud` because it is the hop `Cloud` travels over. Splitting them is what lets the report say *which* hop broke: a dead proxy and a dead platform are two different problems, and one section could only ever render both as the same failure.
A green section is one line. Anything else lists what needs attention, with its cause and its remedy. `-v` unfolds every check.
```
Runtime
Environment ✓ 3 passed, 1 not applicable
Daemon ✓ 2 checks passed
Persistence ⚠ Disabled at your request (user_opt_out) [OL-1513]
The daemon will not restart after a logout, a reboot, or a crash.
found in : [supervision] disabled_reason = "user_opt_out"
to fix : Run `openlatch supervision enable` to re-arm it.
Update ✓ Daemon is serving the installed version (0.1.18)
Platform
Connection ✓ via HTTP proxy proxy.corp:8080 (set by: env)
Cloud ✓ Connected: http://localhost:5173 (0 event(s) forwarded)
Telemetry · Disabled by user (opt-out honoured)
```
### Exit codes
| 0 | Healthy |
| 1 | Something enabled is not working |
| 2 | Usage error |
| 3 | Resource not found |
| 4 | Permission denied |
| 5 | Conflict — `OL-1501` only, because systemd's `RestartPreventExitStatus=5` keys off it |
| **7** | **Degraded** — everything runs, but something is switched off or not at full capability |
| 130 | Interrupted |
`7` matters: `openlatch doctor && deploy` must not succeed on a host where nothing is captured or enforced.