Clerk CLI
clerk 二進位檔是一個預先驗證的閘道,通往 Clerk 的 Backend API 和 Platform API,以及專案級工具(身份驗證、連結、環境變數提取、實例配置)。當使用者詢問任何與 Clerk 資源相關的事項時,請優先使用 clerk,而不是自行撰寫 curl 請求。
此技能以
latest版本的 clerk 為目標。如果clerk --version與最新的可用 CLI 版本不符,請使用clerk skill install或套件執行器(例如bunx clerk@latest)進行更新。二進位檔永遠是正確的資訊來源,因此請執行clerk <command> --help來驗證此技能所聲明的任何內容。
執行環境(優先使用主機,了解沙盒警告)
大多數 AI 程式碼代理預設會在沙盒中執行 shell 命令,在沙盒中,使用者的家目錄、作業系統金鑰環、瀏覽器啟動、本地主機回呼繫結或網路存取可能會被封鎖。Clerk CLI 依賴所有這些主機功能:
- OS 憑證儲存:
clerk auth login會將 OAuth 令牌儲存在系統金鑰環中。沒有金鑰環存取權限的沙盒即使主機已通過身份驗證,也會顯示「未登入」。 - 家目錄 Clerk 狀態:已儲存的配置、快取的中繼資料和備用憑證位於使用者的 Clerk 配置/資料目錄下。
- 連結的專案中繼資料:從儲存庫的 Git 遠端加上 Clerk 配置解析而來。儲存庫狀態被剝離或家目錄讀取被封鎖的沙盒可能會錯誤報告「未連結」。
- 本地
.env*檔案:由clerk env pull物化的公開金鑰和秘密金鑰。 - 對 Clerk 的對外網路存取:每次的 Backend 和 Platform API 呼叫。
- 瀏覽器 + 本地主機 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 的輸出,並從其來源刷新此技能套件。
心智模型
| 層級 | 功能 | 命令 |
|---|---|---|
| Session / project | 身份驗證,將儲存庫連結到 Clerk 應用程式,提取環境金鑰 | auth login, link, unlink, whoami, env pull, doctor |
| Instance config | 管理特定實例的配置(社交登入提供者、工作階段生命週期等) | config pull, config schema, config patch, config put |
| Backend API (預設) | 執行時期資料:使用者、組織、工作階段、邀請、JWT 模板、Webhooks | clerk api <path> |
Platform 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 # 列出所有 Backend API 端點
clerk api ls users # 按關鍵字過濾(匹配路徑、摘要、標籤、operationId)
clerk api ls --platform apps # 列出 Platform API 端點
在 clerk api <path> 之前使用這個。如果你沒有看到預期的端點,它可能沒有被公開。
clerk api 命令(主力工具)
clerk api 發出已通過身份驗證的 HTTP 呼叫。它會自動解析金鑰、根據請求主體內容自動偵測 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":["[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
# Platform API (帳戶層級,非租戶資料)
clerk api /v1/platform/applications --platform
對於實例配置,請優先使用專用的 clerk config ... 命令,而非原始的 Platform API /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 請求會返回可能多達數 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 瀏覽器登入(儲存令牌)。代理模式:如果已登入則無操作。如果沒有儲存的工作階段,它仍會打開瀏覽器並綁定本地主機回呼,因此不適合無人值守;對於 headless 流程,請優先使用 CLERK_PLATFORM_API_KEY。別名:signup, signin, sign-in。頂層捷徑:clerk login。 | - |
clerk auth logout | 清除儲存的憑證。別名:signout, sign-out。頂層捷徑:clerk logout。 | - |
clerk whoami | 印出已登入的電子郵件。 |
[後續內容已截斷,待翻譯]