Clerk CLI は何をしますか?
clerk バイナリは、ClerkのバックエンドAPIおよびプラットフォームAPIへの事前認証済みゲートウェイであり、プロジェクトレベルのツール(認証、リンク、env pull、インスタンス設定)も提供します。ユーザーがClerkリソースに触れることを要求した場合、curl を手動で作成する代わりに、まず clerk を使用してください。
このスキルは、
clerkのlatestバージョンを対象としています。clerk --versionが利用可能な最新CLIと一致しない場合は、clerk skill installまたは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への発信ネットワークアクセス: すべてのバックエンドAPIおよびプラットフォームAPI呼び出し。
- ブラウザ + localhost OAuthコールバック:
clerk auth loginには両方が必要です。
エージェントモードでは、CLIはホスト依存のライブラリ境界でベストエフォートの1回警告チェックを実行するようになりました。ホストのみのClerk状態またはシステム機能が利用できないことを検出すると、次のメッセージが出力されます。
エージェントモードでは、ホストのみのClerk状態またはシステム機能が利用できない可能性があります。これはサンドボックス実行である可能性があります。
auth、link、env、またはAPIの失敗を信頼する前に、ホストシェルでこのコマンドを再実行してください。
この警告は信頼できるものとして扱ってください。コマンドは続行される可能性がありますが、その呼び出しからのauth、link、env、設定、API、ブラウザ、またはOAuthコールバックの失敗は、同じコマンドをホストで再実行するまで信頼できません。
次のコマンドは、サンドボックスではなく、ユーザーのホストシェルで実行することを推奨します。
clerk doctor、clerk whoami、clerk auth login、clerk link、clerk env pull、clerk apps ...、clerk config ...、clerk api ...。
コマンドが誤ってサンドボックスで実行され、「ログインしていません」、auth_required、「リンクされていません」、envの欠落、キーチェーン/ファイル許可エラー、またはネットワーク障害が報告された場合、その結果を信頼できるものとして扱わないでください。それに基づいて行動したり、ユーザーに報告したりする前に、ホストで再実行してください。
CLIの呼び出し
clerk コマンドを実行する前に、どのバイナリを呼び出すかを決定し、その選択をセッションの残りの間固定します。
# 1. スキルの対象バージョンと一致するグローバルインストール済みバイナリを優先します。
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コマンドを実行する前に、CLIが認証され、リンクされ、正常であることを確認します。
clerk --version # バイナリがPATH上にあることを確認
clerk doctor --json # 構造化されたヘルスチェック; 何か失敗した場合は終了コード1
常に最初に clerk doctor --json を実行してください。 これにより、一般的なセットアップの失敗(ログインしていない、プロジェクトがリンクされていない、キーが不足している、CLIバージョンが古い)を事前に検出できるため、後続のコマンドが混乱を招くエラーで失敗するのを防ぎます。エージェントモードでは、Clerkのホスト側設定/認証情報ディレクトリが書き込み可能でない場合に警告する Host execution チェックも含まれます。これは、現在の呼び出しがサンドボックス化されている可能性があることを示す標準的なシグナルです。
各結果には、name、status(pass/warn/fail)、message、オプションの detail、オプションの remedy(修正方法)、オプションの fix(自動修正可能な問題のラベル)があります。それを解析して対処するか、ユーザーに提示します。Host execution が警告した場合は、同じサンドボックス実行からのauth/link/env/APIの失敗を信頼する前に、ホストでコマンドを再実行してください。後続のコマンドの動作がおかしくなった場合は、clerk doctor --json を再実行してください。
clerk --version がこのスキルがカバーするよりも新しいCLIを報告する場合は、最初に clerk <command> --help を信頼し、ソースからこのスキルバンドルを更新してください。
メンタルモデル
| レイヤー | 機能 | コマンド |
|---|---|---|
| セッション / プロジェクト | 認証、リポジトリをClerkアプリにリンク、環境キーをプル | auth login、link、unlink、whoami、env pull、doctor |
| インスタンス設定 | 特定のインスタンスの設定(ソーシャルプロバイダー、セッションの有効期限など)を管理 | config pull、config schema、config patch、config put |
| バックエンドAPI(デフォルト) | ランタイムデータ:ユーザー、組織、セッション、招待状、JWTテンプレート、ウェブフック | clerk api <path> |
プラットフォームAPI(--platform) | アカウントレベル:アプリケーション、インスタンス、請求 | clerk api --platform <path> |
プロジェクトは clerk link を介してアプリケーションに「リンク」されます。リンクされると、ほとんどのコマンドはリポジトリのgitリモートからターゲットアプリと開発インスタンスを自動的に解決します。別のものをターゲットにするには、--app <id> や --instance dev|prod|<instance_id> を渡します。完全な解決順序については、references/auth.md を参照してください。
エンドポイントを発見する - 暗記しない
CLIにはClerk OpenAPIカタログが同梱されています。パスを推測する代わりに、常に動的にエンドポイントを発見してください。
clerk api ls # すべてのバックエンドAPIエンドポイントを一覧表示
clerk api ls users # キーワードでフィルタリング(パス、要約、タグ、operationIdに一致)
clerk api ls --platform apps # プラットフォームAPIエンドポイントを一覧表示
clerk api <path> の前にこれを使用してください。期待したエンドポイントが表示されない場合、それはおそらく公開されていません。
clerk api コマンド(主力)
clerk api は認証されたHTTP呼び出しを行います。キーを自動解決し、ボディの有無からメソッドを自動検出し、標準入力をサポートし、--dry-run で変更をプレビューできます。
# GETリクエスト
clerk api /users # ユーザーを一覧表示
clerk api /users/user_abc123 # 1人を取得
clerk api /users?limit=5&order_by=-created_at # クエリパラメータはインラインで機能
# 変更リクエスト
clerk api /users -d '{"email_address":["[email protected]"]}' # POST(ボディから自動検出)
clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}'
clerk api /users/user_abc123 -X DELETE
# ファイルまたは標準入力からのボディ
clerk api /users --file payload.json
cat payload.json | clerk api /users
# 常に変更をプレビューする
clerk api /users/user_abc123 -X DELETE --dry-run
clerk api /users/user_abc123 -X DELETE --yes # 確認後に確認をスキップ
# 特定のアプリ/インスタンスをターゲットにする
clerk api /users --app app_abc123 --instance prod
# デバッグ時にレスポンスヘッダーを含める
clerk api /users --include
# プラットフォームAPI(アカウントレベル、テナントデータではない)
clerk api /v1/platform/applications --platform
インスタンス設定については、生のプラットフォームAPI /config パスよりも、専用の clerk config ... コマンドを優先してください。これらは、生のエンドポイント形式よりもクリーンにドライラン、差分表示、確認を処理します。
変更を実際に実行する前に、常に --dry-run を実行してください。 その後、--dry-run なしで再実行します(確信がある場合は --yes を追加します)。エージェントモードでは、インタラクティブな確認はバイパスされるため、--dry-run が破壊的な呼び出しに対する唯一の安全策です。
JSONボディは有効なJSONである必要があります。 CLIは不正なペイロードを検証して拒否します。
エンドポイントパスは /v1/ プレフィックスがあってもなくても指定できます - どちらもバックエンドAPI呼び出しで機能します。CLIが正規化します。
具体的なパターン(ユーザーの一覧表示/フィルタリング、組織の作成、なりすましセッションなど)については、references/recipes.md を参照してください。
大きな出力の検査(コンテキストを溢れさせない)
users list、apps list、config pull、およびほとんどの clerk api GETは、数キロバイトまたはメガバイトになる可能性のあるペイロードを返します。本番テナントには数千人のユーザーがいることがよくあります。インスタンス設定は数百のフィールドに及ぶ可能性があります。これらの応答を会話に読み込むと、コンテキストウィンドウを無駄に消費します。最初に応答をファイルに保存し、次に jq を使用して必要なものだけをクエリしてください。
# 1. レスポンスを保存します。ユーザーリストのページサイズを最大化するには --limit 250 を使用します。
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. 必要なものだけを検査します。
jq '.data | length' /tmp/users.json # 現在のページサイズ
jq '.hasMore' /tmp/users.json # さらにページはありますか?
jq '.data[0] | keys' /tmp/users.json # ユーザー構造を一度発見
jq '.data[] | {id, email_addresses}' /tmp/users.json # いくつかのフィールドに射影
jq '[.data[] | select(.banned)] | length' /tmp/users.json # 行を読まずに集計
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)'
cat / head でファイルを表示するのは、1回限りのデバッグのために生の構造を本当に見る必要がある場合のみにしてください。ページを移動するときは、各ページを独自のファイル(例:page-${offset}.json)に書き込んで、個々のページを独立して検査可能に保ってください。
コアコマンド一覧
| コマンド | 目的 | 主要なフラグ |
|---|---|---|
clerk init | プロジェクトにClerkをスキャフォールディングします。--starter は、Next.js、React Router、Astro、Nuxt、TanStack Start、React、Vue、JavaScriptのブートストラップのみをサポートします。 | --framework、--pm、--name(--starter と併用)、--app、--starter、-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 | ログインしているメールアドレスを表示します。 |
…(翻訳のため省略)
(ドキュメントの残りの部分は、元のSKILL.mdの完全なローカライズを提供します。上記は翻訳された主要セクションです。)