CLI

Ongrid envía dos binarios:

• ongrid — el cloud manager. Corre dentro del contenedor del manager.
• ongrid-edge — el agente edge. Corre como servicio systemd en hosts Linux.

Ambos están diseñados para configurarse vía variables de entorno (Variables de entorno), no flags. La superficie CLI es intencionadamente pequeña — apenas suficiente para imprimir la versión y un resumen de ayuda. Cualquier cosa que parezca un flag en despliegues de producción probablemente fue seteada como env ONGRID_* en /etc/ongrid-edge/ongrid-edge.env o deploy/docker-compose.yml.

ongrid (manager)

Lee cada env var ONGRID_* que el binario reconoce, abre sus listeners, y corre hasta SIGINT / SIGTERM. No hay argumentos requeridos ni subcomandos.

Flags

El manager no expone flags documentadas. El único manejo de argv es el estándar del runtime Go: cualquier flag desconocida se ignora. Las futuras flags de ops-tooling (forzar migraciones, dumpear config, regenerar admin bootstrap) están trackeadas bajo la label ops en GitHub.

Modelo de proceso

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

Shutdown graceful: el manager cablea SIGINT / SIGTERM al contexto raíz de su errgroup. Todas las goroutines paran ante cancel de contexto; los requests HTTP en vuelo tienen hasta 10 segundos para terminar.

ongrid-edge (agente)

El binario edge soporta dos flags antes de que cualquier startup env-driven ocurra. Se manejan en el tope mismo de main() para que impriman y salgan incluso en un host mal configurado.

Flag	Alias	Comportamiento
--version	-v	Imprime ongrid-edge <version> y sale 0.
--help	-h	Imprime ongrid-edge <version> más un hint de una línea sobre configuración de systemd, luego sale 0.

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

$ ongrid-edge --version
ongrid-edge v0.7.167

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

No hay flag --config /path. Cada setting viene del entorno. La unit systemd carga /etc/ongrid-edge/ongrid-edge.env vía EnvironmentFile=; para runs ad-hoc (dev en macOS, debugging) los seteas en tu shell.

Env requerido para arrancar

El agente bootea independientemente, pero solo puede hacer trabajo útil una vez que estos tres están seteados:

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>

Modelo de proceso

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)

El agente no forkea. Los plugins son procesos hijo first-class manejados por el supervisor in-process; si un plugin crashea, el supervisor lo reinicia con backoff exponencial y reporta el fallo en el siguiente heartbeat (visible en la página Edges como 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

Desinstalar

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

Elimina el binario, el archivo env, la unit systemd, los binarios de plugin bajo /usr/local/lib/ongrid-edge/, pero preserva /var/log/ongrid-edge/.

Flags de debug vía env

Estos no tienen flags CLI pero son útiles de saber:

Variable	Efecto
ONGRID_LOG_LEVEL=debug	cambia slog a debug; dobla el volumen de log de heartbeat
ONGRID_EDGE_PLUGIN_BIN_DIR=...	sobrescribe el directorio de binarios de plugin (default /usr/local/lib/ongrid-edge)
ONGRID_EDGE_PLUGIN_WORK_DIR=...	sobrescribe los dirs runtime del plugin (default /var/lib/ongrid-edge/plugins)
ONGRID_EDGE_UPGRADE_STAGE_DIR=""	deshabilita el staging de whole-bundle de ADR-024 (setea vacío)
NO_COLOR=1	elimina códigos ANSI de la salida de install.sh (usado por el installer, no por el agente)

install.sh (el installer curl-pipe)

Técnicamente no es un binario, pero tiene un CLI que vale la pena documentar. Uso:

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	Requerida	Descripción
--access-key=KEY	sí (install)	access key por-edge (de la UI del manager)
--secret-key=SECRET	sí (install)	secret matcheante
--server-edge-addr=HOST:PORT	sí (install)	endpoint del túnel (broker frontier)
--server-http-addr=HOST[:PORT]	sí (install)	front door de nginx; usado para descargas de binarios y self-check
--uninstall	no	detiene y elimina el agente (preserva /var/log/ongrid-edge/)
-h, --help	no	imprime uso

Env que lee

Variable	Default	Efecto
ONGRID_INSTALL_WAIT	20	segundos a esperar a que el agente loguee "registered with cloud" antes de declarar éxito
NO_COLOR	unset	deshabilita colores ANSI

Códigos de exit

• 0 — instalado y registrado (o desinstalado).
• 1 — install completado pero el registro no ocurrió (red, keys malas); usa journalctl -u ongrid-edge -f para diagnosticar.
• 2 — invocación mala (flag requerida faltante).

Ver también

• Variables de entorno — la superficie real de configuración.
• Linux (edge) — detalles de la unit systemd, qué deja el installer en disco.
• REST API — la superficie que el manager expone a clientes.