インスタンス自身のカタログが駆動する、一つのCLI。
ingactl はAPIサーフェスをハードコードしません。接続先インスタンスからコマンドカタログを同期するため、 サーバーが提供するルートは再ビルドなしでCLIに現れます。契約、必要権限、プロジェクトIDの配置場所も含まれます。 人にとって便利な同じ性質が、エージェントによる安全な操作も可能にします。
実際のセッション
以下は、開発インスタンスに対して実行した無編集のセッションです。同期、アーティファクト生成、検索、契約確認、ドライラン——認証情報はCLI自身が伏せ字にします。
インストール
CLIは単一のバイナリクレートとしてリポジトリに含まれます。
cargo build --release -p ingactl # → target/release/ingactl
cp target/release/ingactl ~/.local/bin/接続
プロファイルは ~/.config/ingadb/config.toml に保存されます。資格情報のスコープは一つのワークスペースです。 複数ワークスペースに所属する場合は、それぞれにプロファイルを作り --profile で切り替えます。
# トークン — 長期利用、スコープ付き、失効可能、本人として監査
ingactl auth login --url http://localhost:9876 --token cut_...
# メールアドレスとパスワード — 有効期限付きセッショントークン
ingactl auth login --url http://localhost:9876 --email [email protected]
# パスワード: INGADB_PASSWORD。未設定なら非表示プロンプト
# --workspace <name|id> ワークスペースを選択（既定: 最初のもの）
ingactl auth status # ID、ワークスペース、権限を表示CIでは INGADB_URL と INGADB_TOKEN を設定します。環境変数はプロファイルより優先されます。
基本ループ
すべての呼び出しは、ルート検索、正確な契約確認、解決済みリクエストのプレビュー、実行という同じ四段階を通ります。
ingactl api search causal # 1. 候補ルートを検索
ingactl api show data/causal-path # 2. 契約と権限（本人の ✓/✗）
# + プロジェクトIDの渡し方
ingactl api call data/causal-path --project 'packaging-line' --param node_id=E_BEARING --dry-run # 3. 解決済みリクエストを確認
ingactl api call data/causal-path --project 'packaging-line' --param node_id=E_BEARING -o json # 4. 実行- 本文はカタログ例から始まり、
--set a.b=valueでJSONをマージ、--set-strで文字列を強制、--file body.jsonで全置換します。 --param k=vはクエリパラメータを追加します。--project <name|id>は名前を解決し、ルートが要求する場所へIDを配置します。?id=と?project_id=を推測する必要はありません。- 破壊的ルートは先に確認します。
--yesで省略可能です。権限不足は警告しますがブロックせず、最終判断はサーバーが行います。 - 出力は
-o table|json|raw。TTYでは表、パイプ時はJSON。非ゼロ終了コードは{"error": ...}エンベロープを示します。
因果ストアを照会
これらの読み取りルートは、ストアから因果に関する問いへ直接回答します。計算は決定論的で、元のリビジョンが付与されます。
| ルート | 回答内容 |
|---|---|
data/tree/search | ツリーのイベントとゲートをラベルまたはIDで全文検索。 |
data/tree/summary | 全ノード、構造、最上位ゲート、最新分析の有無を一回で取得。 |
data/causal-path | 任意のノードから最上位ゲートまでの因果経路。 |
data/importance | 一つのイベントのFussell-Vesely重要度、寄与、含まれるカットセット。 |
data/cutset | 一つのカットセットに含まれるイベントのラベル、確率、親ゲート。 |
data/event-evidence | 一つのツリーイベントに関連付けられたインシデント。 |
data/analysis | 鮮度状態と正確な changes_since 差分を含む完全な計算済みビュー。 |
pipeline/what-if | 入力を上書きしたモデルを、書き込みなしで計算。 |
projects/overview | 統計、分析状態、上位寄与要因を含むプロジェクト概要。 |
エージェント向け
ingactl skill は同期済みカタログから、エージェント向けの操作ガイドを生成します。 環境確認の「ステップ0」、検索 → 表示 → ドライラン → 実行 のループ、インスタンスが実際に 提供するルートから組み立てた実行例、そしてエラー種別と対処の一覧表。 データから生成されるため、ガイドがデプロイの実態からずれることはありません。
ingactl skill # ガイドを標準出力へ
ingactl api schema # カタログ形式のバージョン — 解析前に確認
ingactl completions zsh # シェル補完（bash|zsh|fish|powershell|elvish）--format と --out を使えば、エージェントが参照する場所へ 同じガイドをそのまま書き出せます。
mkdir -p .claude/skills/ingadb
ingactl skill --format claude-skill --out .claude/skills/ingadb/
# → wrote .claude/skills/ingadb/SKILL.md（YAMLフロントマター付き）
ingactl skill --format agents-md --out .
# → wrote ./AGENTS.md
ingactl padmin skill --format claude-skill --out . # プラットフォーム層も同じフラグ形式は三つ。plain（既定、標準出力）、claude-skill（name/description フロントマター付きのSKILL.md）、agents-md（AGENTS.md）。--out にディレクトリを渡すと既定の ファイル名（SKILL.md / AGENTS.md / ingactl-skill.md）で原子的に書き込み、 書き込んだパスを表示します。実行例とルート一覧はカタログに追従するため、ingactl sync の後に再生成してください。
無人実行を安全にするガードレール:
- 権限の事前確認。
api showは呼び出し元が各ルートの権限を持つか表示し、最終判断はサーバーが行います。 - すべてをドライラン。
--dry-runは送信せず、メソッド、URL、本文、秘匿化済み認証を含む解決済みリクエストを表示します。 - 例示本文ガード。
--set/--fileなしの変更呼び出しはカタログ例をそのまま送るため、対話実行では確認し、スクリプトは--yesなしなら明確に失敗します。 - 破壊的ルートを確認。 カタログで破壊的と指定されたルートだけが確認を求め、読み取りルートは求めません。
- 型付き失敗。 エラーはJSONエンベロープと非ゼロ終了コードで届き、エージェントは文章ではなくデータで分岐できます。
複合ワークフロー
二つのコマンドが一般的な複数ステップ処理をまとめ、完了まで監視します。
ingactl analyze --project 'packaging-line' # 分析ジョブ → 監視
ingactl jobs list --project 'packaging-line'
ingactl jobs watch <job-id>正確性を保つ仕組み
カタログはサーバーバイナリ内に含まれ、/api/schema/catalog でバージョン付き提供されます。 ルート別権限はサーバー自身の /api/schema/rbac から取得します。ingactl sync が両方を更新するため、api show は古くなったコピーではなくインスタンスの規則を報告します。サーフェス変更時はカタログバージョンが変わり、 CLIはキャッシュミス時に再同期します。
プラットフォーム管理 — ingactl padmin
ワークスペース、ユーザー、メンバーシップ、プラットフォームトークンを扱うプラットフォーム層は、 独自のプロファイルと資格情報を持つ別コマンド名前空間です。この分離は意図的に構文へ組み込まれています。 同じコマンド文字列が両方で有効になることはなく、ワークスペースコマンドはプラットフォーム資格情報を拒否し、その逆も同様です。 各 padmin コマンドは、実行前に誰として動作するかをstderrへ表示します。
# Day 0: 新規インスタンスから利用可能なワークスペースログインまでを一コマンドで
ingactl padmin init --url https://ingadb.example.com --workspace acme --user-email [email protected]
# 以後の接続: セッション（7日で失効）またはスコープ付きcpt_ トークン
ingactl padmin login --url <url> --email [email protected]
ingactl padmin status
# プロビジョニング
ingactl padmin workspace create 'Acme'
ingactl padmin user create [email protected] # 仮パスワードを一度だけ表示
ingactl padmin membership assign --user-id <id> --workspace-id <id> --role Analyst
ingactl padmin token mint ci --scope read --scope workspaces --expires-days 90- 同じ検索ループ。
ingactl padmin api search|show|callとingactl padmin skillはプラットフォームカタログ上で動作します。セッションはすべて通過し、トークンはルートのスコープドメインごとに確認されます。 - 名前入力による確認。 ワークスペース削除では名前の再入力を求め、オートメーションでは
--yesを使えます。 - シークレットは一度だけ表示。 仮パスワードと発行済み
cpt_トークンは一度だけ表示し、キャッシュへ保存しません。 - 資格情報で資格情報を管理しない。 トークン管理にはプラットフォーム管理者セッションが必要で、トークン自身はトークンを発行・失効できません。
CLIのすべての動作はプレーンHTTPです。同じカタログとRBACエンドポイントを任意のクライアントから利用できます。APIリファレンスを参照してください。