agenteye CLI はデータ（セッション、イベントログ、評価）のクエリと、組織管理（API キー、ユーザー、設定、アラート、インシデント、保存済みクエリ）を担います。チェックの自動化、ObservabilityのCI組み込み、またはコーディングエージェントによる本番環境の検査といった用途に活用してください。すべてのコマンドは --json フラグをサポートしているため、プロンプトからの手動操作でも、コーディングエージェント（Claude Code、Cursor）がシェルアウトして結果をパースする場合でも同様に機能します。
1つのバイナリで以下が可能です：
- データの読み取り:
sessions、events、evals、errors（時間、エージェント、環境、スコアでフィルタリング）。 - 組織管理:
keys、users、settings、alerts、incidents。 - 分析の実行: 保存済み SQL とアドホッククエリランナー（
query）。 - AI アシスタントへの問い合わせ: ダッシュボードでチャットできる読み取り専用のアナリストと同じもの（
agent）。
注意: これはagenteyeCLI であり、コレクターデーモン（agenteye-collector）とは別のツールです。CLI はダッシュボードと通信し、コレクターはイベントをサーバーに送信します。
クイックスタート
ゼロから最初の結果を得るまで4行で完了します。CLI をダッシュボードに向け、サインインし、本人確認を行い、直近1日の実行を取得します：jq にパイプして加工するか、--json を外してボックス形式のカラー表示にしてください。各行には実行のステータスと、評価者がスコアリングしている場合はメトリクスのスコアが含まれます（ここでは省略）：
インストール
CLI はagenteye という名前の公開 PyPI パッケージです。常に独自の依存関係を持てるよう、隔離された環境にインストールしてください：
agenteye です：
注意: Failproof AI Observability の Python SDK もagenteyeというディストリビューション名を使用しています。pipxやuv toolでCLIをインストール（共有仮想環境へのpip installではなく）することで、両者の競合を防げます。pip install agenteyeを直接実行することは、同じ環境に SDK がインストールされていない場合に限り問題ありません。
認証
CLI はメールで送信されるワンタイムコードを使ってダッシュボードに認証します：~/.agenteye/cli.json（あなただけが読めるよう、モード 0600）に保存され、デフォルトで24時間有効です。期限切れになった場合は agenteye login を再実行してください。
whoami はセッションが存在しない場合や期限切れの場合でもエラーを出しません。代わりに logged_in: false を返すため、スクリプトやエージェントが安全に認証状態を確認できます（ベースURLが未設定またはダッシュボードに到達できない場合は、ゼロ以外の終了コードを返すことがあります）。
要件: あなたのメールアドレスがダッシュボードへのサインインを許可されている必要があります（Failproof AI Observability の管理者に確認してください）。また、ダッシュボードがベースURLで到達可能である必要があります（設定を参照）。コードをリクエストしても届かない場合、そのメールアドレスはまだダッシュボードアクセスが有効化されていない可能性があります。
組織の選択（マルチテナント）
アカウントが複数の組織に所属している場合は、ログイン時にアクティブな組織を選択してください。選択内容は保存され、以降のすべてのコマンドで使用されます：--org を無視して構いません。複数の組織に所属していて選択しない場合、CLI が一覧を表示し、--org <slug> を付けて再実行するよう求めます。アクティブな組織はすべてのリクエストでダッシュボードに送信され、権限は組織ごとに解決されます。agenteye whoami にはアクティブな組織、その中での権限、およびすべてのメンバーシップが表示されます。
設定
優先順位はフラグ → 環境変数 → 設定ファイルです。デフォルト値はありません。コマンドごと（
--base-url https://agenteye.example.com）または環境変数で一度設定する必要があります（初回 login 後にも保存されます）：
AGENTEYE_HOME を参照します（SDK とコレクターで使用されているのと同じ規約）。設定されている場合、cli.json は $AGENTEYE_HOME/cli.json に配置されます。
自己署名またはプライベートTLS
ダッシュボードが自己署名またはプライベート証明書（例えばロードバランサーのホスト名）で HTTPS 提供されている場合、TLS 検証はCERTIFICATE_VERIFY_FAILED エラーで拒否されます。証明書検証をスキップするには --insecure を渡してください：
--insecure はログイン時に cli.json に保存されるため、以降のコマンドでは自動的に検証をスキップします。フラグを毎回繰り返す必要はありません。検証済みの呼び出しを一回だけ行う場合や、次回のログイン時に検証を再有効化して保存する場合は --secure を渡してください。検証が無効な状態でダッシュボードに接続するコマンドの前には、CLIが警告をstderrに出力します。検証をスキップすると中間者攻撃への保護が失われます。この設定に依存する前に、ダッシュボードへのネットワーク経路（VPN、プライベートサブネットなど）を信頼できることを確認してください。
テレメトリーとプライバシー
注意: 出荷時の CLI は現時点では使用状況テレメトリーを送信しません。マスターキルスイッチがオンになっているため、環境に関わらず何も送信されません。以下のセクションでは、テレメトリーが将来有効化された場合のオプトアウト機能について説明します。仮に有効化されたとしても、テレメトリーは匿名の使用状況分析のみであり、エージェント、セッション、イベントデータは対象になりません：
- エージェント、セッション、イベントデータはお客様のインフラ外に出ることはありません。 報告されるのは CLI の使用状況のみです：コマンドとサブコマンド名（例:
keys create）、使用したフラグの名前（値は含まない）、成功/終了ステータス、所要時間、および変更操作ごとのイベント（例:api_key_created、query_run）で、静的な名前/列挙値と大まかなカウントのみが含まれます。ダッシュボードURL、セッショントークン、メールアドレス、組織スラッグ、リソースID、SQL、キーシークレット、クエリフィルターは絶対に送信されません。オペレーターは不透明な内部IDのみで識別され、メールアドレスは使用されません。 - CLIの環境で
AGENTEYE_ANALYTICS_DISABLED=1を設定することで事前にオプトアウトできます（CLIはクロスツール規約のDO_NOT_TRACK=1にも対応しています）。テレメトリーが有効化された瞬間から効果を発揮するため、プライバシーを重視する環境では恒久的にオプトアウト状態を維持できます。 - テレメトリーが有効化された場合、CLI は PostHog（
https://us.i.posthog.com）に直接送信します。そのホストをブロックしているマシンでは、何も送信されず CLI の動作にも影響はありません。
グローバルオプションと規約
一度読んでおいてください。すべてのコマンドに適用されます。- グローバルオプションはコマンドの前に置きます。
agenteye --json sessionsが正しく、agenteye sessions --jsonは使用法エラーです。グローバルオプションは--json、--base-url、--org、--token、--insecure/--secure、--timeout、--quiet、--no-colorです。 --jsonは純粋な JSON のみを stdout に出力し、それ以外は何も出力しません。 人間向けのステータス行、警告、エラーは stderr に出力されるため、ステータス行が表示される場合でも--jsonの stdout キャプチャはjqへのパイプに汚染されません。--jsonなしの場合は、人間の目向けのボックス形式のカラー表示になります。--helpで調べましょう。 すべてのコマンドとサブコマンドに--help（および-hエイリアス）があります：agenteye -h、agenteye sessions -h、agenteye keys create -h。トップレベルのヘルプには終了コードとグローバルオプションも一覧表示されます。グローバルなマシン可読サーフェスダンプはありません。コマンドごとの--helpと、それぞれのレジストリ向けのagenteye query schema、agenteye settings schemaを使用してください。- スクリプトとエージェントでは確認が自動スキップされます。 作成/更新/削除コマンドはインタラクティブなターミナルでは「本当によいですか？」と確認を求めますが、
--json使用時または stdin が TTY でない場合（TTY はインタラクティブなターミナルセッション; パイプや CI ランナーは違います）は自動的にスキップされるため、スクリプトやエージェントがハングすることはありません。明示的にスキップするには--yes/-yを渡してください。エージェントにはプロンプトが表示されないため、エージェントは破壊的な操作の前に人間に確認を求めるべきです。 - ページネーション: 結果は新しいものが先頭でカーソルページネーション方式です（各ページは次のページ取得に使うトークンを返します）。
--limit N（エイリアス-n）で行数を制限し、デフォルトは50です。--allは自動ページネーション（200行チャンク）を行いますが--limitまでが上限なので、--allのみでも50件で停止します。全件取得するには高い上限を明示的に指定してください：--all --limit 1000。--page-size Nでリクエストごとのチャンクサイズを制御します（最大200）。--cursor <id>で前のページのnext_cursorから再開します。 - 時間フィルター:
--sinceは相対期間を受け付けます：15m、1h、6h、24h、7d、またはall（ダッシュボードのプリセット）。より長い期間やカスタム範囲（例えば直近30日）には--from/--toを使用してください：--sinceをオーバーライドする、Tとタイムゾーンを含む明示的な ISO-8601 UTC タイムスタンプ（例:2026-06-01T00:00:00Z）です。スペース区切りやタイムゾーンなしの値は使用法エラーです。 --fields a,b,c（events、sessions、evals、errorsで使用可能）は、テーブルと--jsonの両方で出力をそれらのキーに限定します。不明な名前は有効な一覧とともに拒否されるため、フィールド名を調べる手軽な方法にもなります。--file payload.json（または--file -で stdin を読み取り）は、リソースが複雑な形状を持つ場合にフル JSON リクエストボディを提供します（alerts create/update、settings set、users create/updateで使用）。保存済みクエリの SQL には代わりに--sql @file.sqlを使用します。- 複数値フィルターはカンマ区切りで、集合としてマッチします（1つのフィルター内は OR、フィルター間は AND）：
--event-type tool_use,tool_result。Click オプションは可変長ではないため、--add a bは動作しません。--add a,bを使用するか、フラグを繰り返すか（--add a --add b）、引用符で囲んでください（--add "a b"）。
コマンドリファレンス
最もよく使う5つのコマンド
日々の作業のほとんどはいくつかの読み取りコマンドで対応できます。まずここから始め、必要に応じて以下の全機能を活用してください：CLI でできることすべて
以下に全機能を示します。CLI には18のトップレベルコマンドがあります。すべての読み取りコマンドは--json とグローバルオプションを受け付けます。agenteye <command> -h（または <command> <subcommand> -h）を実行すると、フラグの完全な一覧と各コマンドの JSON の形状を確認できます。
認証関連: login · logout · whoami · orgs · version · help
orgs はアクティブなテナントを確認・切り替えます：
観察（読み取り専用）: events · sessions · evals · errors · list
これらはいずれも確認を必要としません。共有フィルター：--session-id、--agent-id、--env（--environment ではない）、および時間範囲（--since / --from / --to）。
--score KEY:MIN..MAX（evals で使用可能、sessions では不可）は繰り返し使用でき AND で結合されます。どちらの境界も省略可能です（..0.5 は ≤ 0.5、0.9.. は ≥ 0.9 を意味します）。1リクエストあたり最大20のスコアフィルターです。evals --scores-full は人間向けテーブルのみの表示フラグで、最初の数件と +N カウントの代わりにすべてのスコアペアを表示します。常に完全なスコアオブジェクトを返す --json では効果がありません。1つのセッションを最初から最後まで読むには、イベントトレイルと評価を組み合わせてください：
管理（権限必要）: keys · users · settings · alerts · incidents
keys: API キー。シークレットはローカルで生成され、サーバーに送信（サーバーはハッシュのみ保存）され、作成/再生成時に一度だけ表示されます。その場でキャプチャしてください。--json では key フィールドにのみ表示されます。名前で参照します。
(permission-set ∪ --add) − --remove として機能します。トークンは slug:action（例: events:read）または slug:action.action で1つのリソースに複数展開できます（events:read.add → events:read、events:add）。プリセット：read-only、standard、admin。人間専用の権限（keys:update）はキーに付与できません。
users: 組織のメンバー。メールアドレス（UUID の ID も受け付けます）で参照します。
settings: 固定レジストリ（既存のキーの読み取りと変更のみ可能; 新しいキーの作成は不可）。
alerts: アラート定義。名前で参照します。create は位置引数の NAME とフラグ、または --file でフル JSON ボディを受け付けます。
incidents: アラートインシデント。ID（短縮IDも可）で参照します。show はフルのアクティビティログを表示します。操作前に確認してください。
分析とアシスタント: query · agent
query: 分析ストアに対する保存済み SQL とアドホックランナー。保存済みクエリは名前で参照します。SQL はサーバーサイドで検証されます（SELECT/WITH のみ、ステートメントタイムアウト、行数上限）。
agent: 組み込みの AI アシスタントと対話します（ダッシュボードでチャットできる読み取り専用アナリストと同じもの）。チャットは短いチャット ID（プレフィックス解決）で参照します。
終了コード
これらの終了コードにより CLI をスクリプトで安全に使用できます。コーディングエージェントは
4 で再認証を求めるプロンプトを出したり、5 で不足している権限を通知したりできます。終了コードの処理パターンと JSON 出力の形状については エージェント向け CLI レシピ を参照してください。
次のステップ
- エージェント向け CLI レシピ: CLI を操作するコーディングエージェント向けに書かれた、コピー&ペーストで使えるクエリパターン、
jqワンライナー、--fieldsプロジェクション、終了コード処理、JSON 出力の形状。 - CLI エージェントスキル: この CLI を Claude Code / Codex のインストール可能なスキルとしてパッケージ化し、コーディングエージェントが自然言語のリクエストから Failproof AI Observability を操作できるようにします。
- API キー:
keys create --add …の背後にある権限モデル。 - AI アシスタント:
agent askが対話するアシスタントの有効化。