本記事は「Your Agent Can Better Drive the Auth0 CLI with Agent Mode」を翻訳した記事です。
エージェントが新しいアプリケーションをセットアップする場面を想像してください。CLIで何ができるか全くわからないため、推測を始めます。--helpを実行し、さらに1つ深いレベルで--helpを実行し、それを繰り返します。5回の検索の後、必要なコマンドを見つけます。次に、実際のフィールド名を教えてくれるものがないため、自分で作成したフィールド名を含むペイロードを送信します。APIは400エラーと文章で拒否します。エージェントは文章を読み、再び推測します。
エージェントが操作する以前のAuth0 CLIの姿です。すべてのステップでラウンドトリップが発生し、すべての失敗で推測が必要でした。
CLIは、人がキーボードの前に座り、手動でコマンドを試し、エラーを読み、調整することを想定して構築されました。現在、CLIに到達するトラフィックの多くは、代わりにエージェントから来ています。Claude Code、Cursor、CIジョブなどです。以前の前提により、馴染みのないコマンドはすべて試行錯誤に変わりました。
推測に加えて、スペルミスのあるコマンドはヘルプテキストを出力し、何も問題がなかったかのように0で終了していました。終了コードをチェックするスクリプトは、実行されなかったステップの上に次のステップを構築していました。
エージェントモードは、推測と誤ったシグナルを修正します。本記事で利用可能な機能は以下の通りです。
One Switch, Not Five Flags
エージェントは人間のコーダーとは異なるニーズを持っているため、エージェントに--agent-modeを使用させ、一度にAuth0 CLIを理解し始められるようにします。
auth0 apps list --agent-mode
--agent-mode（または環境変数としてのAUTH0_AGENT_MODE=true）は、構造化JSON出力を有効にし、対話型プロンプトと色を無効にし、実際の失敗時にゼロ以外の終了コードを保証します。
常に指定する必要はありません。 エージェントモードは、フラグ、AUTH0_AGENT_MODE=true、またはCLIが既知のコーディングエージェントによって操作されていることを認識したときに有効になります。エージェントとハーネスは通常、AGENT_NAME=CLAUDE_CODEのような識別子を持つサンドボックス環境でAuth0 CLIを実行します。CLIは自動的に識別子を読み取り、エージェントを検出します。人がCLIコマンドを実行する場合、またはスクリプトやパイプで実行される場合、引き続き通常のテーブルを出力します。
エージェントで試す。 "Auth0 CLIを使用してアプリケーションを一覧表示し、存在しないリソースを一覧表示して、取得した終了コードを教えてください。"
A Map of the Whole CLI in One Call
エージェントは単一のコマンドでCLIで利用可能なすべてのコマンドを取得できます。
auth0 commands --flat # or auth0 commands --detailed
auth0 commands --flatを使用すると、エージェントは実行可能なすべてのコマンドのリストをそれぞれの行に取得します。スキャンやインテントマッチングに最適です。
**--detailed**を使用するすべてのコマンドは、フラグ、引数、デフォルト、認証が必要かどうかなど、完全な呼び出しの形式をエージェントに提供します。
2つのフラグにより、エージェントは何が可能かを見つけるためだけに数回のラウンドトリップを費やす代わりに、1回の呼び出しでセッションの計画全体を構築できます。
エージェントで試す。 "何ができるかを把握し、新しいアプリケーションをセットアップしてください。"
Know the Shape Before You Send It
3つの新しいフラグ、--schema、--data、--queryにより、エージェントは推測せずにリソースを作成および検査できます。アプリケーション、API、ユーザー、ロール、接続、ログ、カスタムドメイン、メールテンプレート、Universal Login、ACUL、クライアントグラント、アクションモジュール、セッション、リフレッシュトークン全体で機能します。以下の機能を確認ください。
auth0 apps create --schema
--schemaは、OpenAPI仕様からライブで取得された、コマンドが期待する正確なペイロードを出力します。ログインする前にも機能するため、エージェントは資格情報を持つ前に呼び出しの形式を確認できます。
auth0 apps create --data '{"name":"My App","app_type":"spa"}'
--dataは、インライン、ファイルから、または標準入力を介してパイプされた1つのJSONオブジェクトとしてペイロード全体を送信します。リクエストがAPIに到達する前にローカルでデータを検証するため、不正な形式のペイロードは、何が間違っているかを正確に示すフィールドレベルの詳細とともに、すぐに失敗します。
auth0 logs list --query '{"per_page":5}'
--queryは、コマンドごとのフラグを記憶する代わりに、APIクエリパラメーターのJSONオブジェクトを使用してリストコマンドをフィルタリングします。
エージェントで試す。 "CLIを使用してbeta-testerというAuth0ロールを作成してください。ペイロードがAPIの期待するものと実際に一致していることを確認してください。"
Failures with a Code, Not Just a Sentence
エージェントが次のステップを把握できるように、より良いエラーを提供します。何か問題が発生すると、以下のブロックに似たものを受け取ります。
{"error":{"code":"validation","reason":"local_validation","message":"...","details":[{"field":"name","reason":"property "name" is missing"}]}}
すべての失敗には、コードが検査して回復できる安定したcodeが含まれます。usage、auth、validation、not_found、rate_limitなどです。その下にはより細かいreasonがあります。上記のlocal_validationは、リクエストがマシンを離れる前に、CLI自体が問題を検出したことを意味します。ペイロードは一度に複数の場所で失敗する可能性があるため、detailsは単一のオブジェクトではなく、失敗した特定のフィールドの配列です。ローカル検証の代わりにAPIからエラーが返される場合、エンベロープにはHTTPステータスコードを含むstatusフィールドも含まれます。エージェントは構造全体で分岐します。何が起こったかを推測するために英語を解析する必要はありません。
エージェントで試す。 "billing-serviceという新しいAuth0 APIをセットアップしてください。"
Keep It Light When It Counts
エージェントモードのデフォルトは、読みやすいインデントされたJSONです。
auth0 apps list --agent-mode --json-compact
大量の実行やトークンに敏感な実行の場合、--json-compactは空白を削除し、同じデータをより高密度で返します。auth0 logs tailのようなストリーミングコマンドは、エージェントモードで自動的にコンパクト形式に切り替わります。
エージェントで試す。 "Auth0アプリを頻繁に一覧表示するループで実行しています。応答にかかるトークンを削減する方法を見つけてください。"
Documentation Without Leaving the Terminal
auth0 docs searchは、CLIから直接Auth0の公開ドキュメントをクエリします。
auth0 docs search "organizations"
ログインは不要です。エージェントモードでは、エージェントが直接取得して読み取ることができる生のMarkdown URLで結果が返されます。解析するHTMLや開くブラウザタブがないため、トークンと時間を節約できます。
エージェントで試す。 "簡単な質問ですが、Auth0 Organizationsは実際にはどのように機能しますか。調べて短いバージョンを教えてください。"
A Couple More Things Worth Knowing
キーチェーンを必要としない資格情報。 AUTH0_DOMAINとManagement APIトークンまたはクライアント資格情報のいずれかとともにAUTH0_CLI_AUTH_MODEを設定すると、CLIはOSキーチェーンに触れたりディスクに書き込んだりすることなく実行されます。キーチェーンを持たないCIランナーやサンドボックス向けに構築されています。
export AUTH0_CLI_AUTH_MODE=env export AUTH0_DOMAIN=<your-auth0-domain> export AUTH0_API_TOKEN=<management-api-token> auth0 apps list
開始する前にエージェントにCLIを教える。 CLIをインストールまたはアップグレードした後、スキルインストールコマンドを実行してコーディングアシスタントにAuth0スキルを追加します。これにより、ライブで発見するのではなく、最初のコマンドで規則をすでに知っている状態になります。
auth0 agent skills install
Try It Today
最新のCLIバージョンにアップグレードし、独自のエージェントをそれに向けます。エージェントモードは、v1.38.0より大きいバージョンのAuth0 CLIで利用可能です。
brew upgrade auth0
フィードバックがある場合は、issueを開いてください。チームが調査します。
まだAuth0アカウントを持たない場合は、無料で作成してください。