Communitygithub.com

Clerk CLI

Clerk CLI(`clerk` バイナリ)を使用して、認証、ユーザー/組織/セッション管理、デプロイ検証、インスタンス設定、環境キー、およびClerkバックエンド/プラットフォームAPIを操作します。

Clerk CLI とは?

このスキルは、ClerkのCLIツール(`clerk` バイナリ)を介して、認証・ユーザー管理・組織管理・セッション管理・デプロイ検証・インスタンス設定・環境変数管理など、ClerkのバックエンドAPIおよびプラットフォームAPIへの完全なアクセスを提供します。Clerkの管理タスク(ユーザー一覧表示、ユーザー作成、組織更新、設定プル、env pull、deploy、doctorなど)や任意のClerk APIリクエストをユーザーが依頼した際に使用します。生のHTTPリクエスト(curlなど)よりもCLIを優先することで、認証、キー解決、アプリ/インスタンスのターゲット指定、フォーマット処理を自動化し、作業効率を大幅に向上させます。AIエージェントモードでは、サンドボックス環境による制限(キーチェーンアクセス、ホームディレクトリ状態、ネットワーク等)を自動検出し警告するため、信頼性の高いホストシェルでの実行を推奨します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-cli

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 loginOAuthブラウザログイン(トークンを保存)。エージェントモード:既にログインしている場合は何もしません。保存されたセッションがない場合でも、ブラウザを開き、localhostコールバックをバインドするため、無人運転はできません。ヘッドレスフローには CLERK_PLATFORM_API_KEY を優先してください。エイリアス:signup、signin、sign-in。トップレベルのショートカット:clerk login。-
clerk auth logout保存された認証情報をクリアします。エイリアス:signout、sign-out。トップレベルのショートカット:clerk logout。-
clerk whoamiログインしているメールアドレスを表示します。

…(翻訳のため省略)

(ドキュメントの残りの部分は、元のSKILL.mdの完全なローカライズを提供します。上記は翻訳された主要セクションです。)

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

deangilmoreremix/videoremix.vip2

Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.

deangilmoreremix/videoremix.vip2

Astro patterns with Clerk — middleware, SSR pages, island components, API routes, static vs SSR rendering. Triggers on: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.

deangilmoreremix/videoremix.vip2

Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests. Use when listing users, managing organizations, or calling any Clerk API endpoint.

deangilmoreremix/videoremix.vip2

Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.

deangilmoreremix/videoremix.vip2

Chrome Extension auth with @clerk/chrome-extension -- popup/sidepanel setup, syncHost for OAuth/SAML via web app, createClerkClient for service workers and headless extensions, stable CRX ID. Triggers on: Chrome extension auth, Plasmo clerk, popup sign-in, syncHost, background service worker token, createClerkClient, headless extension.

deangilmoreremix/videoremix.vip2

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.

deangilmoreremix/videoremix.vip2

Agent skill / project related to launch or product demo video: deangilmoreremix/videoremix.vip2

関連スキル