clerk-cli

Clerk CLI

clerk バイナリは、Clerk の Backend API と Platform API、およびプロジェクトレベルのツール（認証、リンク、環境変数の取得、インスタンス設定）への、事前認証済みゲートウェイです。Clerk のリソースに関する依頼では、curl を独自に組み立てるのではなく、まず clerk を使用してください。

セットアップや init の依頼には、clerk-setup スキルを信頼できる情報源として使用してください。パッケージランナー、アカウント不要の利用、移行、および init 優先のガイダンスは、以下の一般的な運用上の前提条件より優先されます。

このスキルは clerk latest を対象としています。clerk --version の結果が利用可能な最新の CLI と異なる場合は、clerk update で更新するか、bunx clerk@latest などのパッケージランナーから最新バージョンを実行してください。バイナリが常に信頼できる情報源です。このスキルの記述内容を確認するには、clerk <command> --help を実行してください。

実行環境（ホストを優先し、サンドボックスの警告を理解する）

ほとんどの AI コーディングエージェントは、ユーザーのホームディレクトリ、OS のキーチェーン、ブラウザーの起動、localhost コールバックのバインド、またはネットワークアクセスがブロックされるサンドボックスで、シェルコマンドを実行するよう既定で設定されています。Clerk CLI は、これらのホスト機能すべてに依存します。

• OS の認証情報ストア：clerk auth login は、OAuth トークンをシステムのキーチェーンに保存します。キーチェーンにアクセスできないサンドボックスでは、ホストで認証済みでも「未ログイン」と報告されます。
• ホームディレクトリ内の Clerk の状態：保存済みの設定、キャッシュされたメタデータ、フォールバック認証情報は、ユーザーの Clerk 設定ディレクトリおよびデータディレクトリに保存されます。
• リンク済みプロジェクトのメタデータ：リポジトリの Git リモートと Clerk の設定から解決されます。リポジトリの状態が削除されている、またはホームディレクトリへの読み取りがブロックされているサンドボックスでは、「未リンク」と誤って報告される場合があります。
• ローカルの .env* ファイル：clerk env pull によって書き込まれる公開可能キーおよびシークレットキー。
• Clerk への外向きネットワークアクセス：すべての Backend API および Platform API 呼び出しに必要です。
• ブラウザーと localhost OAuth コールバック：clerk auth login には両方が必要です。

エージェントモードでは、CLI はホストに依存するライブラリ境界で、ベストエフォートの一度限りの警告チェックを実行するようになりました。ホストでしか利用できない Clerk の状態やシステム機能にアクセスできないことを検出すると、次の内容を出力します。

Host-only Clerk state or system capabilities may be unavailable in agent mode. This may be a sandboxed run.
Re-run this command on the host shell before trusting auth, link, env, or API failures.

この警告は信頼できるものとして扱ってください。コマンドが続行される場合もありますが、その実行で発生した認証、リンク、環境変数、設定、API、ブラウザー、または OAuth コールバックのエラーは、同じコマンドをホスト上で再実行するまで信頼できません。

次のコマンドはサンドボックスではなく、ユーザーのホストシェルで実行してください。

clerk doctor、clerk whoami、clerk auth login、clerk link、clerk env pull、clerk apps ...、clerk config ...、clerk api ...。

コマンドを誤ってサンドボックスで実行し、Not logged in、auth_required、not linked、環境変数の欠落、キーチェーン／ファイルの権限エラー、またはネットワーク障害が報告された場合、その結果を信頼できるものとして扱わないでください。その結果に基づいて対応したり、ユーザーに報告したりする前に、ホスト上で再実行してください。

CLI の実行

clerk コマンドを実行する前に、使用するバイナリを特定し、セッションの残りの間はその選択を固定してください。

# 1. Prefer a globally installed binary when it matches the skill's target version.
command -v clerk >/dev/null 2>&1 && clerk --version

これが latest または信頼できるバージョンを出力する場合は、セッションの残りの間、clerk をそのまま使用してください。

それ以外の場合は、次の順序でパッケージランナーに切り替えてください（CLI 独自の preferredRunner ロジックと同じく、プロジェクトのロックファイルに対応するランナーが優先されます）。

プロジェクトのパッケージマネージャー	実行方法
bun（bun.lock*）	bunx clerk@latest
npm（package-lock.json）	npx -y clerk@latest
pnpm（pnpm-lock.yaml）	pnpm dlx clerk@latest
yarn >= 2（yarn.lock）	yarn dlx clerk@latest

Yarn Classic（v1）には dlx がありません。そのプロジェクトでは「優先ランナーなし」として扱い、PATH 上にあるリスト内の最初のランナーを使用してください。

公開されている npm パッケージは clerk であり、@clerk/cli ではありません。npm install -g clerk を主な方法として案内しないでください。グローバル CLI が古い場合や、このスキルと異なる動作をする場合は、グローバルインストールをアップグレードするか、上記の latest ランナー形式に切り替えてください。

前提条件（セットアップ以外の操作ではセッション開始時に実行）

clerk-setup に従う場合を除き、セッション中に他の Clerk コマンドを実行する前に、CLI が認証済みで、プロジェクトにリンクされ、正常に動作することを確認してください。

clerk --version               # confirm the binary is on PATH
clerk doctor --json           # structured health check; exit 1 if anything failed

必ず最初に clerk doctor --json を実行してください。 このコマンドは、一般的なセットアップの失敗（未ログイン、プロジェクト未リンク、キーの不足、CLI のバージョンが古い）を事前に検出するため、後続のコマンドで原因の分かりにくいエラーが発生するのを防げます。エージェントモードでは、Clerk のホスト側設定／認証情報ディレクトリに書き込み可能かどうかを警告する Host execution チェックも含まれます。これは、現在の呼び出しがサンドボックス内で実行されている可能性が高いことを示す正式なシグナルです。

各結果には、name、status（pass／warn／fail）、message、任意の detail、任意の remedy（修正方法）、および任意の fix（自動修正可能な問題のラベル）が含まれます。これらを解析して対処するか、ユーザーに提示してください。Host execution が警告を出した場合は、同じサンドボックス内での実行による認証／リンク／環境変数／API エラーを信用する前に、ホスト上でコマンドを再実行してください。後続のコマンドで問題が発生し始めた場合は、clerk doctor --json を再実行してください。

clerk --version がこのスキルの対象より新しい CLI を報告した場合は、まず clerk <command> --help を信頼し、ソースからこのスキルバンドルを更新してください。逆の場合も同様です。--accountless と accountless JSON キーは CLI 3.3 以降で提供されています。古い CLI では --keyless エイリアスを使用するか、アップグレードしてください。

アカウントレスのセットアップ

clerk init の実行に clerk auth login は必要ありません。アカウントレスに対応するフレームワークで、--app を指定しない未認証のブートストラップ、または --app も既存のプロジェクトリンクもない未認証のエージェント実行を行うと、アカウントもブラウザーもフラグも必要とせず、開発用の一時キーを備えた未登録のアカウントレスアプリが作成されます。（既存のプロジェクトでサインアウト状態のユーザーが再実行すると、代わりにログインフローが開始されます。--accountless を指定すると、一時キーを使用する方法が強制されます。）その後、ほとんどのインスタンスコマンドは、そのキーだけで動作します。

使用する前に知っておくべき点が 2 つあります。アカウントレスの方法では、ローカルにある sk_ キーがそのまま使用されます。sk_live_ も対象で、登録済みかどうかは問いません。そのため、実際のアプリを指定する場合は --app <id> を渡してください。また、clerk open が返すのは認証情報と同等の価値を持つクレーム URL であり、ログや PR に貼り付けてはいけません。

アカウントが必要なコマンドと、詳細なルールについては、auth.md を参照してください。

メンタルモデル

レイヤー	役割	コマンド
セッション／プロジェクト	認証、リポジトリと Clerk アプリの紐付け、環境変数キーの取得	auth login、link、unlink、whoami、env pull、doctor
インスタンス設定	特定のインスタンスの設定（ソーシャルプロバイダー、セッションの有効期間など）を管理します	config pull、config schema、config patch、config put
バックエンド API（デフォルト）	実行時データ：ユーザー、組織、セッション、招待、JWT テンプレート、Webhook	clerk api <path>
プラットフォーム API（--platform）	アカウントレベル：アプリケーション、インスタンス、請求	clerk api --platform <path>
フロントエンド API（--fapi）	インスタンスの公開クライアント向け API（clerk-js が呼び出す API）	clerk api --fapi <path>

clerk link を使って、プロジェクトをアプリケーションに「リンク」します。リンクすると、ほとんどのコマンドはリポジトリの Git リモートから対象のアプリと開発インスタンスを自動的に解決します。別の対象を指定するには、--app <id> および／または --instance dev|prod|<instance_id> を渡します。解決順序の詳細は、references/auth.md を参照してください。

エンドポイントを記憶せず、見つけましょう

CLI には Clerk の OpenAPI カタログが含まれています。パスを推測せず、常にエンドポイントを動的に見つけてください。

clerk api ls                  # list every Backend API endpoint
clerk api ls users            # filter by keyword (matches path, summary, tag, operationId)
clerk api ls --platform apps  # list Platform API endpoints

clerk api <path> を実行する前に、これを使ってください。想定していたエンドポイントが表示されない場合、そのエンドポイントは公開されていない可能性があります。

clerk api コマンド（主力コマンド）

clerk api は認証済みの HTTP リクエストを実行します。キーを自動的に解決し、本文の有無からメソッドを自動判定し、標準入力に対応し、--dry-run で変更内容をプレビューできます。

# GET requests
clerk api /users                                  # list users
clerk api /users/user_abc123                      # fetch one
clerk api /users?limit=5&order_by=-created_at     # query params work inline

# Mutating requests
clerk api /users -d '{"email_address":["[email protected]"]}'          # POST (auto-detected from body)
clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}'
clerk api /users/user_abc123 -X DELETE

# Body from file or stdin
clerk api /users --file payload.json
cat payload.json | clerk api /users

# Always preview mutations first
clerk api /users/user_abc123 -X DELETE --dry-run
clerk api /users/user_abc123 -X DELETE --yes      # skip confirmation once you've verified

# Target a specific app/instance
clerk api /users --app app_abc123 --instance prod

# Include response headers when debugging
clerk api /users --include

# Platform API (account-level, not tenant data)
clerk api /v1/platform/applications --platform

# Frontend API (the instance's public client-facing API — what clerk-js calls.
# Unauthenticated; --fapi and --platform cannot be combined, --secret-key is ignored)
clerk api --fapi /environment

人間向けモードでは、引数なしで clerk api を実行すると、対話型のリクエストビルダーが開きます。エージェントモードでは、使用方法のガイダンスを表示して 0 で終了します。そのため、スクリプトでは常にエンドポイント（または ls）を明示的に渡してください。

インスタンス設定には、生の Platform API /config パスではなく、専用の clerk config ... コマンドを優先してください。こちらのほうが、ドライラン、差分表示、確認をよりスムーズに処理できます。

変更を実際に実行する前に、必ず --dry-run を指定してください。 その後、--dry-run を外して再実行します（確実な場合は --yes を追加してください）。エージェントモードでは対話型の確認が省略されるため、破壊的な呼び出しに対する安全策は --dry-run だけです。

JSON 本文は有効な JSON でなければなりません。 CLI は入力を検証し、不正なペイロードを拒否します。

エンドポイントのパスは、/v1/ プレフィックスの有無にかかわらず指定できます。どちらも Backend API の呼び出しで使えます。CLI が正規化します。

具体的なパターン（ユーザーの一覧表示／フィルタリング、組織の作成、偽装セッションなど）については、references/recipes.md を参照してください。

大きな出力の確認（コンテキストを圧迫しない）

users list、apps list、config pull、およびほとんどの clerk api GET は、数キロバイトから数メガバイトにもなるペイロードを返します。本番環境のテナントには数千人のユーザーがいることが一般的で、インスタンスの設定は何百ものフィールドにわたることがあります。これらのレスポンスを会話に読み込むと、メリットがないままコンテキストウィンドウを消費します。まずレスポンスをファイルに保存し、jq を使って必要な情報だけを取得してください。

# 1. Persist the response. Use --limit 250 to maximize page size for users list.
clerk users list --json --limit 250 > /tmp/users.json
clerk apps list --json                > /tmp/apps.json
clerk api /users/user_abc123          > /tmp/user.json

# 2. Inspect only what you need.
jq '.data | length'                       /tmp/users.json   # current page size
jq '.hasMore'                             /tmp/users.json   # are more pages available?
jq '.data[0] | keys'                      /tmp/users.json   # discover the user shape once
jq '.data[] | {id, email_addresses}'      /tmp/users.json   # project to a few fields
jq '[.data[] | select(.banned)] | length' /tmp/users.json   # aggregate without reading rows

jq が利用できない場合は、Python または Node を使用してください。どちらもファイル全体を出力せずにストリーム処理できます。

python3 -c 'import json; d=json.load(open("/tmp/users.json")); print(len(d["data"]), d["hasMore"])'
node -e 'const d=require("/tmp/users.json"); console.log(d.data.length, d.hasMore)'

1 回限りのデバッグで生の構造を確認する必要がある場合にのみ、ファイルに対して cat / head を使用してください。ページを順に処理する場合は、各ページを個別のファイル（例：page-${offset}.json）に書き込み、個々のページをそれぞれ確認できるようにしてください。

主なコマンド一覧

コマンド	目的	主なフラグ
clerk init	Clerk をプロジェクトに導入します。--app を指定しない未認証のブートストラップ、または --app も既存のリンクもない未認証のエージェント実行では、デフォルトで一時的な開発キーを書き込みます。ログインは不要です（アカウントなしでのセットアップを参照）。--starter によるブートストラップは Next.js、React Router、Astro、Nuxt、TanStack Start、React、Vue、JavaScript のみをサポートします。--app／--login と併用する --accountless、および --login と併用する --template／--fresh は、何も導入される前に使用エラーになります。実際のアプリに解決される実行（ログイン中のみの場合も含む）で --template／--fresh を指定すると、ストラテジーの解決後にのみエラーになります。そのため、スターターの実行では導入されたプロジェクトが残ります。	--framework、--pm、--name（--starter と併用）、--app、--starter、--accountless、--login、--template、--fresh、-y、--no-skills
clerk auth login	OAuth ブラウザーログイン（トークンを保存します）。ブートストラップやアカウントなしのインスタンス設定には不要です。エージェントモードでは、すでにログインしている場合は何もしません。保存済みセッションがない場合もブラウザーを開き、localhost のコールバックをバインドするため、無人実行には適しません。ヘッドレスフローでは CLERK_PLATFORM_API_KEY を使用してください。エイリアス：signup、signin、sign-in。トップレベルのショートカット：clerk login。	-
clerk auth logout	保存済みの認証情報を消去します。エイリアス：signout、sign-out。トップレベルのショートカット：clerk logout。	-
clerk whoami	ログイン中のメールアドレスを表示します。	-
clerk link / clerk unlink	このリポジトリを Clerk アプリにリンクするか、リンクを解除します。エージェントモードで unlink を実行するには --yes が必要です。	（--help を参照）
clerk env pull	公開可能キーとシークレットキーをフレームワークの環境ファイルに書き込みます（上書きではなくマージ）。.env.development.local → フレームワーク優先ファイル → .env.local の順に解決します。--file で変更できます。	（--help を参照）
clerk config {pull,schema}	インスタンス設定の JSON、またはその JSON Schema を取得します。	（--help を参照）
clerk config patch	インスタンス設定を部分的に更新（PATCH）します。パッチの対象となるサブリソースをデフォルトに戻すのではなく実際に削除するには、--destructive を指定します。	--app、--instance、--file、--json、--dry-run、--yes、--destructive
clerk config put	インスタンス設定を全面的に置き換え（PUT）ます。削除されたサブリソースをデフォルトに戻すのではなく実際に削除するには、--destructive を指定します。	--app、--instance、--file、--json、--dry-run、--yes、--destructive
clerk apps {list,create}	Clerk アプリを一覧表示または作成します。エージェントモードではデフォルトで JSON を出力します。	（--help を参照）
clerk users（サブコマンドなし）	人間モードでは users の操作を選択する対話型ピッカーを表示します。エージェントモードでは操作一覧を表示して 2 で終了します。エージェントから実行する場合は、必ず明示的なサブコマンドを指定してください。	--app、--instance、--secret-key
clerk users list	厳選された BAPI フラグを使用してユーザーを一覧表示します。JSON 出力（パイプ接続時またはエージェントモードでのデフォルト）は {data, hasMore} 形式のため、呼び出し側は /users/count を使わずにページネーションできます。--limit のデフォルトは 100（最大 250）です。	--limit、--offset、--query、--email-address、--phone-number、--username、--user-id、--external-id、--order-by、--json、--app、--instance、--secret-key
clerk users create	厳選されたフラグまたは未加工の BAPI 本文からユーザーを作成します。どのモードでも確認プロンプトは表示されず、即座に書き込みます。--yes は受け付けますが、効果はありません。安全策は --dry-run のみです。まずこれを使ってプレビューしてください。	--email、--phone、--username、--password、--first-name、--last-name、--external-id、-d, --data、--file、--dry-run、--yes、--json
clerk users open [user-id]	ユーザーのダッシュボードページを開きます。エージェントモードでは user-id が必須で、ブラウザーを起動する代わりに JSON ディスクリプターを表示します。	（--help を参照）
clerk impersonate [user]	デバッグ用にユーザーとしてサインインします。有効期間の短いアクタートークンを作成し、サインイン URL を表示します。エイリアス：clerk imp。clerk auth login が必要です（--secret-key のみでの回避は不可）。すべてのトークンには監査可能性のため cli:<email> が記録されます。[user] には user_... ID、完全一致のメールアドレス、またはあいまい検索語を指定できます。本番環境ではユーザーの MFA を迂回し、偽装クォータを消費する場合があります。まずユーザーに確認してください。	--print、--open、--yes、--expires-in <seconds>（デフォルトは 3600）、--actor <context>、--app、--instance
clerk impersonate revoke <actor-token-id>	保留中のアクタートークンを失効させます。トークンの id は作成時にのみ表示されます（Backend API にはアクタートークン一覧エンドポイントがありません）。そのため、作成時に記録してください。	--app、--instance
clerk open [subpath]	リンク済みアプリのダッシュボードをブラウザーで開きます。エージェントモードでは、開く代わりに JSON ディスクリプターを表示します。	（--help を参照）
clerk deploy	人間モード用の本番環境デプロイウィザードです。エージェントモードでは読み取り専用の JSON 引き継ぎ情報を出力し、ウィザードの実行を人間に依頼する、プロビジョニングを待つ、OAuth を完了する、何もしない、のいずれが必要かをエージェントに伝えます。	--mode agent、--mode human、--verbose
clerk deploy status	読み取り専用のデプロイ検証です。DNS チェックを実行し、ドメインと OAuth の準備状況を集計して報告します。完了時のみ 0 で終了します。エージェントモードではデフォルトで簡易チェックを 1 回実行します。待機を続けるには --wait を指定します。	--mode agent、--wait、--verbose
clerk webhooks listen	ファーストパーティのローカル Webhook トンネルです（stripe listen のようなものです）。Svix リレーの受信 URL を開き、各配信をローカルハンドラーに転送します。認証、リンク済みプロジェクト、Clerk API は不要です。フロー全体は references/recipes.md を参照してください。	--forward-to <url>（必須）、--token <c_token>、-H, --header <k:v>（繰り返し指定可能）、--json（NDJSON）
clerk webhooks token	リレートークン（c_ + 10 個の base62 文字）を発行し、マシン間で安定した listen 受信 URL を固定します：clerk webhooks listen --token "$(clerk webhooks token)" --forward-to ...。	--json
clerk webhooks verify	Webhook 署名をオフラインで検証します（ローカルのみで HMAC を使用し、認証不要）。保存済みの listen イベント行（--delivery @event.json）または 4 つの生値から検証できます。	--secret <whsec>（必須）、--delivery @file、--payload @file、--id、--timestamp、--signature、--json
clerk enable orgs / clerk disable orgs	インスタンスの Organizations を切り替えます。組織機能、コンポーネント、API の使用方法については、clerk-orgs スキルを参照してください。	--force-selection、--auto-create、--max-members <n>、--domains、--dry-run、--yes、--app、--instance
clerk enable billing / clerk disable billing	ユーザーおよび／または組織の課金を切り替えます（デフォルトでは両方）。プラン、価格設定コンポーネント、エンタイトルメントについては、clerk-billing スキルを参照してください。	--for <orgs|users>、--dry-run、--yes、--no-skills（有効化のみ）、--app、--instance
clerk doctor	ヘルスチェック（CLI バージョン、ログイン、リンク、環境、設定、補完。エージェントモードではホスト実行プローブも実行します）。	--json、--spotlight、--verbose、--fix
clerk api [path]	Backend API／Platform API に認証付き HTTP リクエストを送信します。	-X、-d、--file、--dry-run、--yes、--include、--app、--secret-key、--instance、--platform
clerk api ls [filter]	同梱の OpenAPI カタログからエンドポイントを検索します。	（--help を参照）
clerk completion [shell]	シェル補完スクリプト（bash、zsh、fish、powershell）を表示します。	-
clerk update	CLI を最新バージョンに更新します。	--channel、-y、--all
フラグの正確な情報源は clerk <command> --help です。 この表は参考情報であり、仕様ではありません。使い慣れていないコマンドやフラグの組み合わせを実行する前に、セッションごとに一度 clerk <command> --help を実行してください。各コマンドではソース内で setExamples([...]) も定義されており、--help を実行するとコピーして貼り付けられる Examples ブロックが表示されるため、構文を推測する必要はほとんどありません。

エージェントモードの動作（重要）

CLI は、標準出力が TTY でない場合、または --mode agent / CLERK_MODE=agent が設定されている場合に、エージェントモードを自動検出します。エージェントモードでは次のように動作します。

• 対話型プロンプトは無効です。 通常は選択画面が表示されるコマンド（--app を指定しない link、--yes を指定しない unlink、サブコマンドを指定しない users）は、自動的に解決されるか、使用方法エラーで終了します。引数なしの clerk api は使用方法のガイダンスを表示して 0 で終了します。エンドポイント（または ls）を明示的に指定してください。スクリプトから呼び出す場合は、必ず明示的なフラグ（--app、--yes）を指定してください。
• ホスト依存の操作では、呼び出しごとに 1 回、サンドボックス警告が表示されます。 ホームディレクトリ内の Clerk の状態、キーチェーンへのアクセス、ネットワーク経由の Clerk 呼び出し、ブラウザーの起動、localhost OAuth コールバックのセットアップによって、上記の警告が表示されることがあります。表示された場合は、結果を信頼する前に、同じコマンドをホスト上で再実行してください。
• ハーネスがエージェントモードとして明確に認識されない場合は、強制的に指定してください。 CLI の非対話型動作とサンドボックス警告の経路を確実に適用するには、--mode agent または CLERK_MODE=agent を使用してください。
• link は決定的なエージェントフローに対応しています。 エージェントモードでは、clerk link --app <id> で直接リンクします。--app を指定しない場合、CLI はまずキーに基づくサイレント自動リンクを試みます。アプリを一意に特定できない場合は終了し、--app を指定するよう案内します。
• init では clerk-setup に従ってください。 フレームワークのサポート、アカウントなしでの利用、アプリのリンク、移行、ログイン順序に関するガイダンスは clerk-setup が担当し、セットアップ手順の情報源を一本化します。
• --fresh は破壊的な操作です。 一時アプリを置き換え、プロンプトなしで環境キーと .clerk/keyless.json の記録を上書きするため、以前のアプリとそのユーザーが孤立します。init を再実行するだけの目的で指定しないでください。
• エージェントモードでは unlink に --yes が必要です。 isAgent() && !options.yes を条件として判定し、指定されていない場合は使用方法エラーで終了します。これは例外であり、一般的なパターンではありません。次の箇条書きを参照してください。
• 実際に --yes が必須なのは unlink だけです。 それ以外の確認処理はすべて isHuman() && !options.yes として記述されているため、エージェントモードでは確認が完全にスキップされます。変更処理はプロンプトもエラーもなく実行されます。--yes を指定しても問題ありませんが、何も変わりません。安全策として扱わないでください。実際の安全策は --dry-run です。
• エージェントモードでは impersonate に位置引数 [user] が必要です。 検索語に一致するユーザーが複数いる場合は、候補のユーザー ID を一覧表示して 2 で終了します。特定の user_... ID を指定して再試行してください。出力は JSON オブジェクト（{url, id, userId, actor, ...}）です。url をユーザーに提示し、id を記録してください。取り消し用ハンドルを記録できる機会はこのときだけです。
• webhooks listen は長時間実行されます。 バックグラウンドで実行してください。エージェントモード（または --json を指定した場合）では NDJSON が出力されます。最初に ready 行（{type:"ready", relay_url, forward_to}）が 1 行、その後、配信ごとに event 行が 1 行出力されます。各 event 行は clerk webhooks verify --delivery に渡せます。
• doctor --fix は無視されます。 doctor --json の出力にある remedy フィールドを解析し、自分で対応してください。
• apps list と apps create は、パイプ経由の場合、デフォルトで JSON を出力します。
• users も apps と同様に、パイプ経由の場合はデフォルトで JSON を出力します。 エージェントモードでは clerk users list と clerk users create が JSON を出力します。サブコマンドなしの clerk users は、エージェントモードでは使用方法エラーになります。list、create、または open を明示的に指定してください。エージェントモードで clerk users open を実行する場合は、位置引数 user-id が必要です。ブラウザーを起動する代わりに JSON 記述子を出力します。
• deploy にはエージェントへの引き継ぎと検証ゲートがあります。 エージェントモードでは、引数なしの clerk deploy は読み取り専用で、JSON の引き継ぎ情報を出力します。対話型ウィザードを実行することはありません。対話型の標準入力プロンプトが必要なため、Claude や別のエージェントに ! clerk deploy を実行させないでください。必要な場合は、人間に新しいターミナルウィンドウで clerk deploy を実行してもらい、その後 clerk deploy status --mode agent を実行して完了を確認してください。references/agent-mode.md を参照してください。
• --input-json <json|@file|-> は、JSON を任意のコマンドのフラグに展開します（例：clerk init --input-json '{"framework":"next","yes":true}'）。標準入力を使う場合は、明示的な - マーカーが必要です（echo '{"yes":true}' | clerk init --input-json -）。パイプ経由の標準入力だけでは自動検出されないため、シェルループや自身で入力を読み取るコマンド（cat body.json | clerk api …）には影響しません。--input-json は末端のサブコマンドの後に置いてください。詳細なルールは references/agent-mode.md を参照してください。 references/agent-mode.mdに全体の対応表とサンドボックスの詳細があります。

出力形式とエラー

• JSON 出力： apps listとdoctorでは--jsonを指定します。clerk apiではレスポンスボディが生の API JSON なので、そのままjqにパイプできます。
• 終了コード： 0は成功、1は実行時エラー、2は使用方法／検証エラーです。doctorはチェックに失敗した場合に1を返します。
• エラー形式： ユーザー向けのエラーは stderr に1行で出力され、ゼロ以外の終了コードが設定されます。デバッグ時にスタックトレースを表示するには、--verboseを使用します。

自律的な使用に関する安全ルール

1. 操作する前に調査します： clerk api <path>の前にclerk api ls <keyword>を実行します。
2. 変更をプレビューします： すべてのconfig patch、config put、api -X POST/PATCH/PUT/DELETEに--dry-runを指定します。
3. 本番環境では対象を明示します： デフォルトに頼らず--instance prodを指定し、本番環境に変更を加える前にユーザーに確認します。
4. シークレットをコミットしないでください： env pullは.env.localに書き込みます（このファイルは gitignore に追加してください）。シークレットキーをコードやチャットに貼り付けないでください。
5. CLI の不具合を疑う前にdoctor --jsonで診断します。

参考資料

• references/auth.md - 認証フロー、キーの解決順序、ホストとサンドボックスの動作の違い、--app／--instanceによる対象指定、Backend API と Platform API。
• references/recipes.md - Clerk の一般的なタスクで使えるコピー＆ペースト可能なレシピ。
• references/agent-mode.md - エージェントモードの動作対応表、サンドボックスに関する警告の動作、終了コード、エラー形式。