CLI

O Ongrid distribui dois binários:

• ongrid — o cloud manager. Roda dentro do container do manager.
• ongrid-edge — o edge agent. Roda como um serviço systemd em hosts Linux.

Ambos são projetados para serem configurados via variáveis de ambiente (Variáveis de ambiente), não flags. A superfície CLI é intencionalmente pequena — apenas o suficiente para imprimir a versão e um sumário de help. Qualquer coisa que se pareça com uma flag em deploys de produção provavelmente foi setada como env ONGRID_* em /etc/ongrid-edge/ongrid-edge.env ou deploy/docker-compose.yml.

ongrid (manager)

Lê cada env var ONGRID_* que o binário reconhece, abre seus listeners, e roda até SIGINT / SIGTERM. Não há argumentos requeridos nem subcomandos.

Flags

O manager não expõe flags documentadas. O único tratamento de argv é o do runtime Go padrão: qualquer flag desconhecida é ignorada. Flags futuras de tooling de ops (forçar migrações, dumpar config, regenerar admin de bootstrap) são rastreadas sob a label ops no GitHub.

Modelo de processo

ongrid
  ├─ HTTP listener em $ONGRID_HTTP_ADDR (:8080)
  ├─ /metrics listener em $ONGRID_METRICS_ADDR (:9100)
  ├─ SDK geminio service-end disca para $ONGRID_FRONTIER_ADDR (frontier:40011)
  ├─ goroutine do evaluator de alerta (intervalo $ONGRID_ALERT_EVAL_INTERVAL)
  ├─ sampler de pool de DB (tick de 10s)
  └─ investigators em background (uma goroutine por request de investigação)

Health

curl http://localhost:8080/healthz   # sempre 200 uma vez que o server está up
curl http://localhost:8080/readyz    # 200 quando DB + dial frontier estão saudáveis

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: o manager conecta SIGINT / SIGTERM ao contexto raiz do seu errgroup. Todas as goroutines param em cancel de contexto; requests HTTP em andamento ganham até 10 segundos para terminar.

ongrid-edge (agent)

O binário do edge suporta duas flags antes que qualquer startup driven por env aconteça. São tratadas no topo de main() para que imprimam e saiam mesmo num host mal-configurado.

Flag	Alias	Comportamento
--version	-v	Imprime ongrid-edge <version> e sai 0.
--help	-h	Imprime ongrid-edge <version> mais uma dica de uma linha sobre configuração systemd, então sai 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.

Não há uma flag --config /path. Cada setting vem do environment. A unit systemd carrega /etc/ongrid-edge/ongrid-edge.env via EnvironmentFile=; para runs ad-hoc (dev no macOS, debugging) você as define no seu shell.

Env requerida para iniciar

O agent vai bootar de qualquer jeito, mas só pode fazer trabalho útil uma vez que esses três estejam definidos:

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 processo

ongrid-edge
  ├─ dial do tunnel para $ONGRID_EDGE_CLOUD_ADDR
  ├─ listener /metrics + /healthz em :9101 (localhost)
  ├─ collector embarcado (gopsutil)
  ├─ supervisor de plugin (subprocess promtail / otelcol-contrib / node_exporter / process-exporter)
  ├─ dispatcher de skill (trata RPCs execute_skill do manager)
  └─ port-forwarder webshell (trata RPCs open_shell do manager)

O agent não dá fork. Plugins são child processes first-class gerenciados pelo supervisor in-process; se um plugin crasha, o supervisor o reinicia com backoff exponencial e reporta a falha no próximo heartbeat (visível na 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

# de um edge rodando:
curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --uninstall

Remove o binário, o arquivo env, a unit systemd, os binários de plugin sob /usr/local/lib/ongrid-edge/, mas preserva /var/log/ongrid-edge/.

Flags de debug via env

Essas não têm flags CLI mas são úteis o suficiente para saber:

Variável	Efeito
ONGRID_LOG_LEVEL=debug	troca slog para debug; dobra o volume de log de heartbeat
ONGRID_EDGE_PLUGIN_BIN_DIR=...	sobrescreve o diretório de binário de plugin (padrão /usr/local/lib/ongrid-edge)
ONGRID_EDGE_PLUGIN_WORK_DIR=...	sobrescreve os dirs de runtime de plugin (padrão /var/lib/ongrid-edge/plugins)
ONGRID_EDGE_UPGRADE_STAGE_DIR=""	desabilita o staging de whole-bundle do ADR-024 (defina vazio)
NO_COLOR=1	remove códigos ANSI da saída do install.sh (usado pelo instalador, não o agent)

install.sh (o instalador curl-pipe)

Tecnicamente não é um binário, mas tem um CLI que vale 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	Obrigatório	Descrição
--access-key=KEY	sim (install)	access key por-edge (da UI do manager)
--secret-key=SECRET	sim (install)	secret correspondente
--server-edge-addr=HOST:PORT	sim (install)	endpoint de tunnel (broker frontier)
--server-http-addr=HOST[:PORT]	sim (install)	porta da frente do nginx; usada para downloads de binário e self-check
--uninstall	não	para e remove o agent (preserva /var/log/ongrid-edge/)
-h, --help	não	imprime uso

Env que ele lê

Variável	Padrão	Efeito
ONGRID_INSTALL_WAIT	20	segundos para esperar que o agent logue "registered with cloud" antes de declarar sucesso
NO_COLOR	não-setado	desabilita cores ANSI

Exit codes

• 0 — instalado e registrado (ou desinstalado).
• 1 — instalação completou mas registro não aconteceu (rede, chaves ruins); use journalctl -u ongrid-edge -f para diagnosticar.
• 2 — invocação ruim (flag obrigatória faltando).

Veja também

• Variáveis de ambiente — a superfície real de configuração.
• Linux (edge) — detalhes da unit systemd, o que o instalador coloca em disco.
• REST API — a superfície que o manager expõe a clients.