clerk-cli

Clerk CLI

clerk 二進位檔是一個預先認證的閘道，通往 Clerk 的後端 API 和平台 API，並提供專案層級工具（認證、連結、環境變數拉取、實例設定）。當使用者詢問任何與 Clerk 資源相關的事項時，優先使用 clerk，而不是手動撰寫 curl。

此技能針對 clerk latest 版本。如果 clerk --version 與最新的可用 CLI 版本不一致，請使用 clerk skill install 或套件執行器（例如 bunx clerk@latest）進行更新。二進位檔始終是權威來源，因此請執行 clerk <command> --help 來驗證此技能所聲明的任何內容。

執行環境（優先使用主機，了解沙箱警告）

大多數 AI 程式碼代理預設在沙箱中執行 shell 指令，在沙箱中，使用者的家目錄、作業系統金鑰鏈、瀏覽器啟動、localhost 回呼綁定或網路存取可能會被封鎖。Clerk CLI 依賴所有這些主機功能：

• 作業系統憑證儲存：clerk auth login 將 OAuth token 儲存在系統金鑰鏈中。沒有金鑰鏈存取的沙箱即使主機已認證，也會回報「not logged in」。
• 家目錄 Clerk 狀態：儲存的設定、快取的中繼資料和備用憑證位於使用者的 Clerk 設定/資料目錄下。
• 連結的專案中繼資料：從儲存庫的 git remote 加上 Clerk 設定解析。儲存庫狀態被剝離或家目錄讀取被封鎖的沙箱可能會錯誤回報「not linked」。
• 本機 .env* 檔案：由 clerk env pull 產生的可發布和密鑰。
• 對 Clerk 的對外網路存取：每次後端和平台 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 回呼失敗都是不可信的，直到你在主機上重新執行相同的指令。

優先在使用者的主機 shell 上執行這些指令，而不是在沙箱中：

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. 優先使用全域安裝的二進位檔，前提是它符合技能的目標版本。
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 版本過舊），避免後續指令因令人困惑的錯誤而失敗。在代理模式下，它還包含一個 Host execution 檢查，當 Clerk 主機端的設定/憑證目錄無法寫入時會發出警告，這是當前呼叫可能處於沙箱中的典型信號。

每個結果都有 name、status（pass/warn/fail）、message、可選的 detail、可選的 remedy（如何修復）以及可選的 fix（可自動修復問題的標籤）。解析這些資訊並採取行動，或將其呈現給使用者。如果 Host execution 發出警告，請在主機上重新執行指令，然後再信任來自相同沙箱執行的任何認證/連結/環境變數/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 範本、webhook	clerk api <path>
平台 API（--platform）	帳戶層級：應用程式、實例、計費	clerk api --platform <path>
前端 API（--fapi）	實例的公開客戶端 API（即 clerk-js 呼叫的）	clerk api --fapi <path>

專案透過 clerk link「連結」到應用程式。一旦連結，大多數指令會從儲存庫的 git remote 自動解析目標應用程式和開發實例。若要指定其他目標，請傳遞 --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                      # 取得單一使用者
clerk api /users?limit=5&order_by=-created_at     # 查詢參數可直接內嵌

# 變更請求
clerk api /users -d '{"email_address":["a@b.co"]}'          # 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（實例的公開客戶端 API — 即 clerk-js 呼叫的。
# 未經認證；--fapi 和 --platform 不能同時使用，--secret-key 會被忽略）
clerk api --fapi /environment

在人類模式下，不帶參數的 clerk api 會開啟互動式請求建構器；在代理模式下，它會列印使用說明並以退出碼 0 結束 — 始終從腳本中明確傳遞端點（或 ls）。

對於實例設定，請優先使用專用的 clerk config ... 指令，而不是原始的平台 API /config 路徑。它們處理乾執行、差異比對和確認的方式比原始端點形式更簡潔。

在實際執行變更之前，始終使用 --dry-run 進行預覽。 然後重新執行（如果你確定，可以加上 --yes）。在代理模式下，互動式確認會被繞過，因此 --dry-run 是破壞性呼叫的唯一安全網。

JSON 主體必須是有效的 JSON。 CLI 會驗證並拒絕格式錯誤的負載。

端點路徑可以帶或不帶 /v1/ 前綴 - 兩者都適用於後端 API 呼叫。CLI 會進行正規化。

請參閱 references/recipes.md 以了解具體模式：列出/過濾使用者、建立組織、模擬登入工作階段等。

檢查大量輸出（不要塞爆你的上下文）

users list、apps list、config pull 和大多數 clerk api GET 請求的回應可能達到數 KB 或 MB。生產環境的租戶通常有數千名使用者；一個實例設定可能包含數百個欄位。將這些回應讀入對話中會浪費上下文視窗，沒有任何好處。先將回應儲存到檔案，然後只使用 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 讀取檔案。在翻頁時，將每個頁面寫入自己的檔案（例如 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 瀏覽器登入（儲存 token）。代理模式：如果已登入則無操作。如果沒有儲存的工作階段，它仍然會開啟瀏覽器並綁定 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，否則會出現確認提示。	--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]	以使用者身分登入進行偵錯：建立一個短期有效的 actor token 並列印登入 URL。別名：clerk imp。需要 clerk auth login（無 --secret-key 繞過方式）— 每個 token 都會標記 cli:<email> 以利稽核。[user] 接受 user_... ID、確切的電子郵件或模糊搜尋詞。在生產環境中，它會繞過使用者的 MFA，並可能計入模擬配額 — 請先與使用者確認。	--print, --open, --yes, --expires-in <seconds>（預設 3600）, --actor <context>, --app, --instance
clerk impersonate revoke <actor-token-id>	撤銷待處理的 actor token。token id 僅在建立時列印（後端 API 沒有 actor token 列表端點），因此請在建立時記錄它。	--app, --instance
clerk open [subpath]	在瀏覽器中開啟已連結應用程式的儀表板。代理模式：列印 JSON 描述符，而不是開啟。	（請參閱 --help）
clerk deploy	人類模式的生產部署精靈。代理模式：發出唯讀的 JSON 交接，並告訴代理是否要要求人類執行精靈、等待佈建、完成 OAuth，或什麼都不做。	--mode agent, --mode human, --verbose
clerk deploy status	唯讀的部署驗證。觸發 DNS 檢查，回報整體網域和 OAuth 就緒狀態，僅在完成時以退出碼 0 結束。代理模式預設執行一次快速檢查；傳遞 --wait 以持續等待。	--mode agent, --wait, --verbose
clerk webhooks listen	第一方本地 webhook 隧道（類似 stripe listen）：開啟一個 Svix relay 收件匣 URL，並將每次傳遞轉發到你的本地處理器。無需認證、無需連結專案、無需 Clerk API。完整流程請參閱 references/recipes.md。	--forward-to <url>（必要）, --token <c_token>, -H, --header <k:v>（可重複）, --json（NDJSON）
clerk webhooks token	產生一個 relay 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）或四個原始值進行驗證。	--secret <whsec>（必要）, --delivery @file, --payload @file, --id, --timestamp, --signature, --json
clerk enable orgs / clerk disable orgs	切換實例上的組織功能。有關組織功能、元件和 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]	對後端/平台 API 的認證 HTTP 呼叫。	-X, -d, --file, --dry-run, --yes, --include, --app, --secret-key, --instance, --platform
clerk api ls [filter]	從內建的 OpenAPI 目錄探索端點。	（請參閱 --help）
clerk completion [shell]	列印 shell 自動完成腳本（bash, zsh, fish, powershell）。	-
clerk update	將 CLI 更新到最新版本。	--channel, -y, --all
clerk skill install	從 CLI 重新安裝內建的 clerk-cli 技能。在此獨立套件中，請直接更新技能來源。	（請參閱 --help）

clerk <command> --help 是標誌的權威來源。 此表格僅為提示，而非規格。在執行不熟悉的指令或標誌組合之前，請在每個工作階段中執行一次 clerk <command> --help。每個指令也在原始碼中定義了 setExamples([...])，--help 會將其呈現為可複製貼上的範例區塊，因此你幾乎不需要猜測語法。

代理模式行為（重要）

當 stdout 不是 TTY，或設定了 --mode agent / CLERK_MODE=agent 時，CLI 會自動偵測代理模式。在代理模式下：

• 互動式提示被停用。 通常會顯示選擇器的指令（不帶 --app 的 link、不帶 --yes 的 unlink、不帶子指令的 users）會自動解析或退出並顯示使用錯誤。不帶參數的 clerk api 會列印使用說明並以退出碼 0 結束；請明確傳遞端點（或 ls）。在腳本化呼叫中始終傳遞明確的標誌（--app, --yes）。
• 主機敏感的操作每次呼叫會發出一次沙箱警告。 家目錄 Clerk 狀態、金鑰鏈存取、對 Clerk 的網路呼叫、瀏覽器啟動和 localhost OAuth 回呼設定可能會觸發上述警告。如果出現，請在主機上重新執行相同的指令，然後再信任結果。
• 如果你的執行環境沒有明確表現為代理模式，請強制指定。 當你希望 CLI 確定性地套用非互動式行為和沙箱警告路徑時，請使用 --mode agent 或 CLERK_MODE=agent。
• link 支援確定性的代理流程。 在代理模式下，clerk link --app <id> 會直接連結。如果沒有 --app，CLI 會先嘗試基於金鑰的靜默自動連結；如果無法明確確定應用程式，它會退出並告訴你傳遞 --app。
• 除非已認證或指定目標，否則 init 在代理模式下永遠不會為你選擇或建立真實的 Clerk 應用程式。 傳遞 --app <id>（或預先連結專案）以認證並連結真實應用程式，或傳遞 --keyless 以在支援無金鑰的框架上引導新專案時使用自動產生的臨時開發金鑰。如果兩者都沒有，代理模式會列印手動設定指引並乾淨退出。
• 在代理模式下，unlink 需要 --yes。 這保留了與其他破壞性指令相同的安全標準，同時仍允許代理以非互動方式完成取消連結。
• 變更仍然需要 --yes，除非你接受無法進行每次呼叫的確認。
• 在代理模式下，impersonate 需要 [user] 位置參數。 如果搜尋詞符合多個使用者，它會以退出碼 2 結束，並列出候選使用者 ID — 請使用特定的 user_... ID 重試。輸出為 JSON 物件（{url, id, userId, actor, ...}）；將 url 呈現給使用者，並記錄 id — 這是記錄撤銷控制代碼的唯一機會。
• webhooks listen 是長時間執行的。 請在背景執行。在代理模式下（或使用 --json），它會發出 NDJSON：一個 ready 行（{type:"ready", relay_url, forward_to}），然後每次傳遞一個 event 行 — 每個事件行都可以傳回給 clerk webhooks verify --delivery。
• doctor --fix 會被忽略。 請自行解析 doctor --json 輸出的 remedy 欄位並採取行動。
• apps list 和 apps create 在管道模式下預設輸出 JSON。
• users 在管道模式下預設輸出 JSON，與 apps 類似。 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，因為精靈需要互動式 stdin 提示。請在需要時要求人類在新的終端機視窗中執行 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 -）；裸管道的標準輸入不會被自動偵測，因此 shell 迴圈和自行讀取的指令（cat body.json | clerk api …）不受影響。將 --input-json 放在葉子子指令之後。完整規則請參閱 references/agent-mode.md。

完整的矩陣和沙箱詳細資訊請參閱 references/agent-mode.md。

輸出格式和錯誤

• JSON 輸出： --json 用於 apps list 和 doctor。對於 clerk api，回應主體是原始的 API JSON，因此可以自由地透過管道傳遞給 jq。
• 退出碼： 0 成功，1 執行時期錯誤，2 使用/驗證錯誤。如果任何檢查失敗，doctor 會回傳 1。
• 錯誤格式： 面向使用者的錯誤會將單一行列印到 stderr，並設定非零的退出碼。偵錯時使用 --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. 使用 doctor --json 進行診斷，然後再假設 CLI 已損壞。

參考資料

• references/auth.md - 認證流程、金鑰解析順序、主機與沙箱行為、--app/--instance 定位、後端與平台 API。
• references/recipes.md - 常見 Clerk 任務的可複製貼上配方。
• references/agent-mode.md - 代理模式行為矩陣、沙箱警告語義、退出碼、錯誤格式。