CLI

Ongrid ships two binaries:

• ongrid — the cloud manager. Runs inside the manager container.
• ongrid-edge — the edge agent. Runs as a systemd service on Linux hosts.

Both are designed to be configured via environment variables (Environment variables), not flags. The CLI surface is intentionally tiny — just enough to print the version and a help summary. Anything that looks like a flag in production deploys was probably set as ONGRID_* env in /etc/ongrid-edge/ongrid-edge.env or deploy/docker-compose.yml.

ongrid (manager)

Reads every ONGRID_* env var the binary recognises, opens its listeners, and runs until SIGINT / SIGTERM. There are no required arguments and no subcommands.

Flags

The manager exposes no documented flags. The only argv handling is the standard Go runtime's: any unknown flag is ignored. Future ops-tooling flags (forcing migrations, dumping config, regenerating bootstrap admin) are tracked under the ops label on GitHub.

Process model

ongrid
  ├─ HTTP listener on $ONGRID_HTTP_ADDR (:8080)
  ├─ /metrics listener on $ONGRID_METRICS_ADDR (:9100)
  ├─ geminio service-end SDK dial to $ONGRID_FRONTIER_ADDR (frontier:40011)
  ├─ alert evaluator goroutine (interval $ONGRID_ALERT_EVAL_INTERVAL)
  ├─ DB pool sampler (10s tick)
  └─ background investigators (one goroutine per investigation request)

Health

curl http://localhost:8080/healthz   # always 200 once the server is up
curl http://localhost:8080/readyz    # 200 when DB + frontier dial are healthy

Stop / restart

docker compose -f deploy/docker-compose.yml restart ongrid
docker compose -f deploy/docker-compose.yml down
docker compose -f deploy/docker-compose.yml up -d

Graceful shutdown: the manager wires SIGINT / SIGTERM to its errgroup's root context. All goroutines stop on context cancel; in-flight HTTP requests get up to 10 seconds to finish.

ongrid-edge (agent)

The edge binary supports two flags before any env-driven startup happens. They are handled at the very top of main() so they print and exit even on a misconfigured host.

Flag	Alias	Behaviour
--version	-v	Prints ongrid-edge <version> and exits 0.
--help	-h	Prints ongrid-edge <version> plus a one-line hint about systemd configuration, then exits 0.

Verbatim from cmd/ongrid-edge/main.go:

$ ongrid-edge --version
ongrid-edge v0.9.0

$ ongrid-edge --help
ongrid-edge v0.9.0
Run as a systemd service. See /etc/ongrid-edge/ongrid-edge.env for config.

There is no --config /path flag. Every setting comes from the environment. The systemd unit loads /etc/ongrid-edge/ongrid-edge.env via EnvironmentFile=; for ad-hoc runs (dev on macOS, debugging) you set them in your shell.

Required env to start

The agent will boot regardless, but it can only do useful work once these three are set:

export ONGRID_EDGE_CLOUD_ADDR=ongrid.example.com:40012
export ONGRID_EDGE_ACCESS_KEY=<from manager UI>
export ONGRID_EDGE_SECRET_KEY=<from manager UI>

Process model

ongrid-edge
  ├─ tunnel dial to $ONGRID_EDGE_CLOUD_ADDR
  ├─ /metrics + /healthz listener on :9101 (localhost)
  ├─ embedded collector (gopsutil)
  ├─ plugin supervisor (subprocess promtail / otelcol-contrib / node_exporter / process-exporter)
  ├─ skill dispatcher (handles execute_skill RPCs from manager)
  └─ webshell port-forwarder (handles open_shell RPCs from manager)

The agent does not fork. Plugins are first-class child processes managed by the in-process supervisor; if a plugin crashes, the supervisor restarts it with exponential backoff and reports the failure on the next heartbeat (visible in the Edges page as health.last_error).

Stop / restart

sudo systemctl restart ongrid-edge
sudo systemctl stop ongrid-edge
sudo systemctl status ongrid-edge
journalctl -u ongrid-edge -f

Uninstall

# from a running edge:
curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --uninstall

Removes the binary, the env file, the systemd unit, the plugin binaries under /usr/local/lib/ongrid-edge/, but preserves /var/log/ongrid-edge/.

Debug flags via env

These do not have CLI flags but are useful enough to know about:

Variable	Effect
ONGRID_LOG_LEVEL=debug	switch slog to debug; doubles the heartbeat log volume
ONGRID_EDGE_PLUGIN_BIN_DIR=...	override the plugin binary directory (default /usr/local/lib/ongrid-edge)
ONGRID_EDGE_PLUGIN_WORK_DIR=...	override the plugin runtime dirs (default /var/lib/ongrid-edge/plugins)
ONGRID_EDGE_UPGRADE_STAGE_DIR=""	disable the ADR-024 whole-bundle staging (set empty)
NO_COLOR=1	strip ANSI codes from install.sh output (used by the installer, not the agent)

install.sh (the curl-pipe installer)

Technically not a binary, but it has a CLI worth documenting. Usage:

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- \
    --access-key=KEY \
    --secret-key=SECRET \
    --server-edge-addr=<host>:40012 \
    --server-http-addr=<host>:443

Flags

Flag	Required	Description
--access-key=KEY	yes (install)	per-edge access key (from manager UI)
--secret-key=SECRET	yes (install)	matching secret
--server-edge-addr=HOST:PORT	yes (install)	tunnel endpoint (frontier broker)
--server-http-addr=HOST[:PORT]	yes (install)	nginx front door; used for binary downloads and self-check
--uninstall	no	stop and remove the agent (preserves /var/log/ongrid-edge/)
-h, --help	no	print usage

Env it reads

Variable	Default	Effect
ONGRID_INSTALL_WAIT	20	seconds to wait for the agent to log "registered with cloud" before declaring success
NO_COLOR	unset	disable ANSI colors

Exit codes

• 0 — installed and registered (or uninstalled).
• 1 — install completed but registration did not happen (network, bad keys); use journalctl -u ongrid-edge -f to diagnose.
• 2 — bad invocation (missing required flag).

See also

• Environment variables — the real configuration surface.
• Linux (edge) — systemd unit details, what the installer drops on disk.
• REST API — the surface the manager exposes to clients.