CLI

Ongrid は 2 つのバイナリを出荷します：

ongrid —— クラウド manager。manager コンテナ内で動く。
ongrid-edge —— edge エージェント。Linux ホスト上で systemd サービスとして動く。

両方ともフラグではなく 環境変数（環境変数）で設定するよう設計されています。CLI 表面は意図的に小さく —— バージョンとヘルプサマリーを表示するのに十分なだけです。本番デプロイでフラグのように見えるものは、ほぼ間違いなく /etc/ongrid-edge/ongrid-edge.env か deploy/docker-compose.yml で ONGRID_* env として設定されたものです。

`ongrid`（manager）

バイナリが認識するすべての ONGRID_* env var を読み、リスナーを開き、SIGINT / SIGTERM まで動きます。必須の引数もサブコマンドもありません。

フラグ

manager はドキュメント化されたフラグを公開しません。唯一の argv 処理は標準 Go ランタイムのもの：未知のフラグは無視されます。将来の ops ツールフラグ（マイグレーション強制、設定ダンプ、ブートストラップ admin の再生成）は GitHub の ops ラベル下で追跡されています。

プロセスモデル

text

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)

ヘルス

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

停止 / 再起動

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 シャットダウン：manager は SIGINT / SIGTERM を errgroup のルートコンテキストに配線します。すべての goroutine が ctx キャンセルで止まります。in-flight HTTP リクエストは終了に最大 10 秒得ます。

`ongrid-edge`（agent）

edge バイナリは env 駆動の起動前に 2 つのフラグをサポートします。main() の最上部で処理されるので、誤設定ホスト上でも表示して exit します。

フラグ	エイリアス	挙動
`--version`	`-v`	`ongrid-edge <version>` を表示して exit 0。
`--help`	`-h`	`ongrid-edge <version>` + systemd 設定に関する 1 行ヒントを表示して exit 0。

cmd/ongrid-edge/main.go から逐語：

text

$ 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.

--config /path フラグはありません。すべての設定は環境から来ます。systemd unit が EnvironmentFile= 経由で /etc/ongrid-edge/ongrid-edge.env をロードします。アドホック実行（macOS 上の開発、デバッグ）ではシェルで設定します。

起動に必須の env

エージェントはどうあれ起動しますが、これら 3 つが設定されたときだけ意味ある作業ができます：

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>

プロセスモデル

text

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)

エージェントは fork しません。プラグインはプロセス内 supervisor が管理するファーストクラス子プロセス。プラグインがクラッシュすると、supervisor が指数バックオフで再起動し、次のハートビートで失敗を報告します（Edges ページで health.last_error として可視）。

停止 / 再起動

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

アンインストール

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

バイナリ、env ファイル、systemd unit、/usr/local/lib/ongrid-edge/ 下のプラグインバイナリを削除しますが、/var/log/ongrid-edge/ は保持します。

env 経由のデバッグフラグ

これらは CLI フラグを持ちませんが、知っておくと便利です：

変数	効果
`ONGRID_LOG_LEVEL=debug`	slog を debug に切り替え。ハートビートログ量を倍にする
`ONGRID_EDGE_PLUGIN_BIN_DIR=...`	プラグインバイナリディレクトリオーバーライド（デフォルト `/usr/local/lib/ongrid-edge`）
`ONGRID_EDGE_PLUGIN_WORK_DIR=...`	プラグインランタイム dir オーバーライド（デフォルト `/var/lib/ongrid-edge/plugins`）
`ONGRID_EDGE_UPGRADE_STAGE_DIR=""`	ADR-024 全バンドルステージングを無効化（空に設定）
`NO_COLOR=1`	install.sh 出力から ANSI コードを削除（インストーラが使用、エージェントは使わない）

install.sh（curl-pipe インストーラ）

技術的にはバイナリではありませんが、ドキュメントに値する CLI を持ちます。使い方：

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

フラグ

フラグ	必須	説明
`--access-key=KEY`	はい（インストール時）	edge ごと access キー（manager UI から）
`--secret-key=SECRET`	はい（インストール時）	マッチする secret
`--server-edge-addr=HOST:PORT`	はい（インストール時）	トンネルエンドポイント（frontier broker）
`--server-http-addr=HOST[:PORT]`	はい（インストール時）	nginx フロントドア。バイナリダウンロードとセルフチェックに使用
`--uninstall`	いいえ	エージェントを停止して削除（`/var/log/ongrid-edge/` を保持）
`-h`、`--help`	いいえ	使い方を表示

読む env

変数	デフォルト	効果
`ONGRID_INSTALL_WAIT`	`20`	成功宣言前に「registered with cloud」とログするのを待つ秒数
`NO_COLOR`	未設定	ANSI 色を無効化

終了コード

0 —— インストール + 登録（またはアンインストール）成功。
1 —— インストール完了したが登録は起きなかった（ネットワーク、誤キー）。診断には journalctl -u ongrid-edge -f を使用。
2 —— 誤った呼び出し（必須フラグ欠落）。

CLI ​

ongrid（manager） ​

フラグ ​

プロセスモデル ​

ヘルス ​

停止 / 再起動 ​

ongrid-edge（agent） ​

起動に必須の env ​

プロセスモデル ​

停止 / 再起動 ​

アンインストール ​

env 経由のデバッグフラグ ​

install.sh（curl-pipe インストーラ） ​

フラグ ​

読む env ​

終了コード ​

関連 ​

CLI

`ongrid`（manager）

フラグ

プロセスモデル

ヘルス

停止 / 再起動

`ongrid-edge`（agent）

起動に必須の env

プロセスモデル

停止 / 再起動

アンインストール

env 経由のデバッグフラグ

install.sh（curl-pipe インストーラ）

フラグ

読む env

終了コード

関連