Communitygithub.com

deangilmoreremix/videoremix.vip2

操作 Clerk CLI(`clerk` 二進位檔)以進行身份驗證、使用者/組織/工作階段管理、部署驗證、實例配置、環境金鑰以及任何 Clerk Backend 或 Platform API 呼叫。當使用者提及 Clerk 管理任務時使用。

videoremix.vip2 是什麼?

此技能作為操作 Clerk CLI (`clerk` 二進位檔) 的權威介面,Clerk CLI 是 Clerk 後端 API、平台 API 和專案級工具(例如身份驗證、連結和環境變數提取)的預先驗證閘道。其主要優勢是自動處理令牌解析、金鑰解析和格式設定,讓開發者免於手動建立 `curl` 請求。此技能支援各種平台,包括主要的 AI 編碼代理(如 Claude Code、Coder 和 Codex),並提供在沙盒與主機環境中執行的明確指引,其中包含關於主機特定功能(如作業系統金鑰環、主目錄 Clerk 狀態和本地主機回呼繫結)可能無法使用的警告。其工作流程強調透過 `clerk doctor --json` 進行初始健康檢查、使用 `clerk api` 進行動態端點探索,並透過 `--dry-run` 旗標和將大型輸出保存到檔案進行檢查(例如使用 `jq`)來安全地處理變更操作。此技能還記錄了在全局安裝與基於專案鎖定檔案的套件管理器之間解析正確 `clerk` 二進位檔的過程,並涵蓋了從使用者管理到實例配置的核心命令。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 模板、Webhooksclerk 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 loginOAuth 瀏覽器登入(儲存令牌)。代理模式:如果已登入則無操作。如果沒有儲存的工作階段,它仍會打開瀏覽器並綁定本地主機回呼,因此不適合無人值守;對於 headless 流程,請優先使用 CLERK_PLATFORM_API_KEY。別名:signup, signin, sign-in。頂層捷徑:clerk login。-
clerk auth logout清除儲存的憑證。別名:signout, sign-out。頂層捷徑:clerk logout。-
clerk whoami印出已登入的電子郵件。

[後續內容已截斷,待翻譯]

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

相關技能