ii999/agentenv

agentenv は何をしますか？

agentenv は、通常の値と認証情報への参照を保持するローカルTOML設定ファイルを読み取ります。認証情報の値は、環境変数、プラットフォームの認証情報ストア、または外部コマンドに保持され、ファイル内には決して保存されません。CLIは値の読み取り、検証済みのフォーマット保持書き込みによるファイル編集、選択された値を一時的な環境に注入してターゲットプロセスを起動します。

agentenv に依存する前に、command -v agentenv でCLIが利用可能であることを確認してください。もし不足している場合は、その旨を伝えて停止してください。設定ファイルを直接読み取って動作を再現しようとしてはなりません。

厳格なルール

• 解決された認証情報の値を、表示、ログ出力、永続化、または要約してはなりません。agentenv run を、それ自身の環境を開示するように選ばれたターゲット（env, printenv, set, sh -c 'echo $VAR'、または環境をファイルに書き込むこと）で起動してはいけません。これらはすべて違反です。
• 秘密の値を設定ファイルに書き込んではなりません。set は通常の値のためです。credential add は定義のみを書き込みます。credential set は値を保存する唯一のパスであり、プラットフォームの認証情報ストアに保存し、ファイルには保存しません。
• プロファイル、エントリ、フィールド、または認証情報が欠落している場合は、そのことを明示的に報告してください。フィールド名を推測したり、静かにプロファイルを切り替えたり、別の認証情報を代用したりしないでください。
• 設定はCLIを通じて読み取り、TOMLファイルを直接開いてはいけません。これにより、プロファイル選択、認証情報の間接参照、および検証が適用されます。
• credential fill がブラウザフィールドに値を書き込んだ後、そのフィールドを読み返したり、その値を評価したり、それを表示するスクリーンショットを撮ったりしてはいけません。フィル結果のみを報告できます。

設定の読み取り

上から順に作業し、このセッションですでに行った手順はスキップします。

1. agentenv project status --json — プロファイル依存の設定を読み取る前に、最も近いプロジェクトファイルとその信頼状態を検出します。その報告は、終了コードが 5 または 6 の場合でも標準出力に書き込まれます。終了コード 2 の場合は標準出力が空になります。
2. agentenv list --json — プロファイルとエントリを検出します。agentenv list --profiles は、プロファイルを選択せずにプロファイル名を一覧表示します。
3. agentenv show <entry> --json — 使い慣れないエントリを使用する前に検査します。認証情報フィールドは reference メンバー（credential://<name> または credential://<name>?as=<ENV>）として表示され、値として表示されることはありません。
4. agentenv get <path> — 1つの通常のスカラー値を読み取ります。配列またはテーブルの場合は --json を使用します。認証情報フィールドを読み取ると、参照文字列が返され、秘密は返されません。
5. agentenv find <needle> --json — 何かがどこにあるかわからない場合に、エントリ名、フィールド名、説明、および文字列値を検索します。--all-profiles を追加してすべてのプロファイルを検索します。

パスは、選択されたプロファイル内のドット区切りのフィールドセグメントです（例：llm.model）。句読点やスペースを含むセグメントは引用符で囲みます：servers."my host".port。プロファイルはパスの一部ではありません。--profile <NAME> で選択します（優先順位：--profile、次に AGENTENV_PROFILE、次に信頼されたプロジェクトファイルのピン、次にファイル内の default_profile）。これは読み取り、run、set、unset に適用されます。--create-profile は明示的な --profile を必要とし、ピンは決して使用しません。

プロジェクトスコープの設定

agentenv は、作業ディレクトリからファイルシステムルートに向かって移動しながら、最も近い通常の .agentenv.toml を検出します。ファイルは閉じた選択専用のスキーマを持ちます：version = 1、オプションの空でない profile、およびオプションの [requires.<entry>] テーブル（空でない reason と、オプションでエントリ相対の fields（存在する場合は空でない）を持ちます）。サイズは64 KiBに制限されており、値、認証情報定義、inject テーブル、または credential:// 文字列を含めることはできません。

プロジェクトファイルは、その正確な内容が承認されるまで無効です。agentenv project status、agentenv project allow、および agentenv project revoke を使用して、検査、承認、および承認の削除を行います。承認はユーザー状態ディレクトリに保持され、リポジトリの外部にあります。ファイルを編集すると、再び信頼されなくなります。信頼されていないファイルは、1つのstderr通知を除いて、通常のコマンドには影響しません。

project グループ以外のコマンドでは、--no-project または空でない AGENTENV_NO_PROJECT を使用して検出をバイパスします。このバイパスは project status、project allow、または project revoke には決して適用されず、これらは常に最も近いファイルを検出します。

project status --json は、プロジェクト状態が利用不可、無効、または信頼されていない場合は終了ステータス 5 で、要件が満たされていないか確認できない場合は終了ステータス 6 で、意図的にそのレポートを標準出力に書き込みます。これは、失敗時にJSONが空になる通常のルールの例外です。終了コード 2 は設定エラー（プロジェクトファイルの検証エラーを含む）をカバーし、このコマンドでは標準出力を空のままにします。

認証情報が必要なコマンドの実行

run を1つ以上の --with <entry> フラグとともに使用し、ターゲットは -- の後に指定します：

agentenv run --with llm -- llm-client request
agentenv run --with llm --with kubernetes -- deploy-tool sync

各 --with エントリは、その認証情報参照と inject テーブル（環境名をそのエントリの通常フィールドにマッピングします）を提供します。認証情報は、参照が ?as=<ENV> オーバーライドを持たない限り、その inject_as 名で注入されます。ターゲットが受け取る環境名を確認するには、agentenv credential list --json から inject_as を読み取り、agentenv show <entry> --json から inject テーブルと reference メンバーを読み取ります。

ターゲットのstdin/stdout/stderrは変更されずに通過し、その終了ステータスが返されます。競合する注入（2つのソースが1つの環境名をターゲットにする）は、何も解決または起動する前に終了コード4で中止されます。

--pure を追加すると、キュレーションされた最小限の環境でターゲットを起動します：固定のプラットフォームベース（PATH、HOME、ロケール、AGENTENV_*、および同様のプロセスに重要な名前）、繰り返し可能な --keep <NAME> で明示的に運ばれる変数、および注入 — 呼び出し元シェルからの他のものは何もありません。親で設定されていない保持された名前はstderrで報告され、実行は続行されます。--pure はターゲットの環境のみをフィルタリングします。これはサンドボックスではなく、ターゲット内のネストされた agentenv 呼び出しは同じ設定を解決します。認証情報の解決は --pure によって変更されません：command プロバイダーのサブプロセスは完全な親環境を保持します。

設定の書き込み

ユーザーが設定の記録を依頼した場合に使用します：

agentenv init                            # 設定ファイルを作成；上書きを拒否
agentenv set <path> <value>              # 1つの値を書き込む；中間テーブルを作成
agentenv set <path> <value> --type int|float|bool|json
agentenv set llm.model gpt-5 --description "Default LLM."   # エントリも作成
agentenv set <path> <value> --profile dev --create-profile "Dev profile."
agentenv unset <path>                    # 1つのフィールドまたはテーブルを削除

すべてのエントリには説明が必要です。新しいトップレベルエントリを作成するには、同じ set で --description が必要です。不明なプロファイルはエラーですが、明示的な --profile とともに --create-profile を渡した場合はエラーになりません。すべての書き込みは最初にファイル全体で検証され、結果が無効な場合は拒否されるため、拒否された書き込みはファイルをバイト単位で同一に保ちます — 診断メッセージを報告し、盲目的にバリエーションを再試行しないでください。

検証は、token、password、secret、api_key、または private_key という名前（または接尾辞）の文字列フィールドへの平文値を拒否します：そのようなフィールドは credential:// 参照を保持する必要があります。ユーザーが保存する秘密を渡した場合は、代わりに認証情報として定義して保存し（次のセクション）、それを参照してください。

認証情報の管理

agentenv credential list --json          # 定義＋浅いステータス；何も解決しない
agentenv credential check <name>         # 1つの認証情報を解決；利用可能性のみ報告
agentenv credential add <name> --description "<text>" --provider env \
    --env-var <NAME> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider keychain \
    --service <service> --account <account> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider command \
    --argv <arg> [--argv <arg> ...] --inject-as <ENV>
agentenv credential set <name> --input dialog --json  # ローカルエントリを開く；結果を待つ

新しい認証情報の順序：credential add で定義を追加し、次にキーチェーンプロバイダーの場合は credential set で値を保存し、次にエントリフィールドから credential://<name> として参照します。Env およびコマンド認証情報は、外部システムから値を取得します。credential set はそれらには適用されません。

ローカルキーチェーンエントリの場合は、PTYなしで credential set <name> --input dialog --json を起動します。ユーザーにローカルウィンドウで値を入力して保存するよう伝えます。コマンドを実行し続け、その完了を待ちます。これにはツールセッションの中断をまたぐ場合も含みます。開いたウィンドウは、保存が完了したことを意味しません。開いているエントリウィンドウやクリップボードを検査、キャプチャ、読み取り、または自動化してはいけません。ユーザーはそこで値を入力して確認し、コマンドは完了メタデータのみを返します。

依存タスクは、終了コード0とJSONの status: "stored" の後でのみ続行します。status: "cancelled" は、確認された保存なしでエントリが終了したことを意味します。それを報告し、依存アクションを停止したままにします。status: "failed" には、秘密ではない reason が含まれます。診断を報告します。store-unconfirmed は書き込みが発生した可能性があることを意味するため、以前の値が変更されていないと主張したり、自動的に再試行したりしないでください。起動/設定エラーは、JSONが出力される前に終了する可能性があります。ゼロ以外の終了または結果の欠落は失敗として扱います。すでに進行中の保存は、コマンドが返される前に完了します。確認された書き込みは、その書き込み中にユーザーがクローズを要求した場合でも、stored を報告します。

ダイアログは、agentenvを実行しているマシン上でグラフィカルセッションを必要とします。リモートまたはヘッドレスホストでは、その制限を説明し、ユーザー自身がそのホストのターミナルで agentenv credential set <name> --input terminal を実行し、完了を確認するように依頼してください。Agentが所有するPTYやstdinパイプを代用しないでください。チャットで値を尋ねたり、argv、環境変数、コマンドパイプ、またはファイルに配置したりしないでください。ターミナル入力はローカルの表示切り替えをサポートしているため、その画面出力はAgentのツールの範囲外に留めておく必要があります。

ローカルでの使用には keychain または command プロバイダーを推奨します。env は環境を継承するすべてのプロセスに値を公開するため、CIに適しています。

Docker Composeとの連携

非秘密設定は .env に保持します。認証情報は、それを必要とするプロセスのためだけに注入し、Composeが注入された変数を受け取るようにします：

agentenv run --with llm -- docker compose up

services:
  app:
    image: alpine:3.20
    environment:
      - OPENAI_API_KEY

${OPENAI_API_KEY} 補間もComposeでサポートされています。シークレットを含む env_file: は使用しないでください。ファイル内に認証情報が永続化されます。

ブラウザフィールドへの認証情報の入力

credential fill は、操作中のページに保存された認証情報が1つの入力フィールドで必要な場合に使用します。ブラウザのデバッグプロトコルを通じて値を書き込みます。ナビゲーションと送信は、自身のブラウザツールで続けて行います。

agentenv credential fill --capabilities --json
agentenv credential fill <name> --backend cdp --endpoint http://127.0.0.1:<port> \
    --page-url <exact page URL> --selector '<css of the one input>' --json

手順：

1. --capabilities が cdp バックエンドを利用可能としてリストしていることを確認します。ブラウザはループバックChrome DevTools Protocolエンドポイントを公開している必要があります（--remote-debugging-port と非デフォルトの --user-data-dir で起動されたChromium、またはブラウザツールがすでに使用しているエンドポイント）。存在しない場合はその旨を伝えてください。ブラウザを起動したり、値を貼り付けたりしないでください。
2. ブラウザツールでページに移動し、ページの正確なURLとターゲット入力のみに一致するCSSセレクターを渡します。URLに揮発性のクエリパラメーターが含まれる場合は --page-match origin-path を追加し、フィールドへの途中の各iframeには --frame-selector を、同じURLが複数のコンテキストで開かれている場合は --context-index を追加します。
3. そのタブのDevToolsを閉じ、入力中はトレース、スクリーンキャスト、HAR、およびビデオ録画をオフにしてください。agentenvは開いているDevToolsウィンドウでのみ失敗します。他のレコーダーは検出できないためです。
4. コマンドを実行します。成功すると {"version":1,"backend":"cdp","effect":"field-filled"} のみが出力されます。フィールドの以前の内容は置き換えられ、ページは通常の入力イベントを受け取りました。自身のツールで送信を続行します。

environment 使用を許可する認証情報のみが入力できます。値は、制御文字、行区切り文字、または双方向制御文字を含まない、最大8,192バイトの単一行である必要があります（そうでない場合は value-unsupported）。コマンドプロバイダーはターミナルなしで実行され、末尾の1つの改行は削除されます。空、NUL、または非UTF-8のプロバイダー出力は認証情報エラー（終了コード4）です。最初のアクセス時のキーチェーン認証ダイアログを含む操作全体は、--timeout-ms（デフォルト30,000）の下で実行されます。ユーザーがそのようなダイアログをクリックして通過する必要がある場合は、タイムアウトを引き上げてください。credential fill はフィールドを検証したり、フォームを送信したり、ログインしたりしません。効果を報告し、観察しなかった成功を報告しないでください。

失敗理由はstderrに出力されます（credential-fill: <reason>: <message>）。終了コード8、何も変更されていません：backend-unavailable、permission、connect-failed、version-unsupported、recording-conflict、context-absent、page-absent、page-ambiguous、frame-absent、frame-ambiguous、frame-invalid、target-absent、target-ambiguous、target-hidden、target-disabled、target-readonly、target-unfillable、target-changed、value-unsupported、timeout、cancelled。終了コード11、フィールドに値が含まれている可能性があります：timeout、cancelled、または値が送信された後のdelivery-failed、および配信された値の後のcleanup-unconfirmed。

特権実行

リクエストが設定された sudo-target を使用する場合、計画、確認、実行、作成、またはローテーションの前に references/sudo-execution.md を読んでください。

…

[翻訳用に切り詰められました]