halton-meter status · Halton Meter docs

Health summary for the four Halton Meter processes — daemon, watchdog, edge, userenv — plus ports, sentinels, and install mode. JSON output for scripts.

halton-meter status prints a Rich table of every component a Halton Meter install touches: the four launchd processes, the three TCP listeners, the system-proxy state, the sentinel files, and the install mode. With --json the same content comes out as a single JSON object, suitable for scripts and dashboards.

For the deep diagnostic — every layer of cert trust, certifi patch, plist registration, port binding, sentinel state — use halton-meter doctor instead. status is the fast overview; doctor is the forensic walkthrough.

Synopsis

halton-meter status [--json]

What it checks

The implementation is halton_meter.lifecycle.status. Per row:

daemon process — PID via launchctl list com.haltonlabs.meter
watchdog process — PID via the watchdog label
edge process — PID via the edge label; expected up regardless of daemon state
userenv login agent — PID; expected - (one-shot)
mitmproxy listener — port internal_port (default 8090) bound on loopback
FastAPI listener — port api_port (default 8765) bound on loopback, /health returns 200
system-proxy state — per-interface networksetup -getsecurewebproxy
sentinel files — proxy-managed, apps-managed, install-mode
install mode — env-only / apps / full

A healthy run

~ — halton-meter status

$ halton-meter status

halton-meter v0.1.24 · status

component             state          detail
────────────────────────────────────────────────────────────────────
install-mode          apps           ~/.halton-meter/install-mode
daemon                healthy        PID 80214 · com.haltonlabs.meter
watchdog              healthy        PID 80215 · com.haltonlabs.meter.watchdog
edge                  healthy        PID 80213 · 127.0.0.1:8081
userenv               applied        last applied at login
mitmproxy listener    bound          127.0.0.1:8090
fastapi listener      bound          127.0.0.1:8765
system-proxy          off            (apps mode)
sentinels             consistent     proxy-managed: -  apps-managed: ✓

JSON output

For scripts and dashboards:

~ — halton-meter status --json

$ halton-meter status --json
{
"version": "0.1.22.21",
"install_mode": "apps",
"daemon": { "state": "healthy", "pid": 80214, "label": "com.haltonlabs.meter" },
"watchdog": { "state": "healthy", "pid": 80215 },
"edge": { "state": "healthy", "pid": 80213, "port": 8081 },
"ports": { "edge": 8081, "internal": 8090, "api": 8765 },
"system_proxy": { "state": "off" },
"sentinels": { "proxy_managed": false, "apps_managed": true }
}

The JSON shape is stable across patch releases — adding fields, never removing or renaming.

Common states

State	Meaning	Next step
`healthy`	Component up and responding	None
`stopped`	Process registered with launchd but not running	`halton-meter start`
`unbound`	Listener port not held	`halton-meter doctor`
`inconsistent`	Sentinel says one mode, system state says another	`halton-meter init <correct-mode>` to reconcile
`unknown`	Layer couldn’t be probed	Almost always cert/permission; `doctor` will identify

Reading the underlying state by hand

~ — by-hand state inspection

$ launchctl list com.haltonlabs.meter           # PID + LastExitStatus
$ launchctl list com.haltonlabs.meter.edge
$ launchctl list com.haltonlabs.meter.watchdog
$ launchctl print "gui/$(id -u)/com.haltonlabs.meter"
$ cat ~/.halton-meter/effective-ports.json      # the chosen tuple
$ cat ~/.halton-meter/install-mode              # env-only / apps / full

launchctl list returns "PID" = <int> when alive and "PID" = -; when registered but not running.

What’s next

halton-meter doctor — the deep diagnostic when status shows anything not healthy
Troubleshooting — the failure-by- failure repair guide keyed on what status reports
Fail-open behaviour — why a stopped daemon with a healthy edge is the expected state during stop