Communitygithub.com

Clerk CLI 操作指南

操作 Clerk CLI(`clerk` 二进制文件)进行身份验证、用户/组织/会话管理、部署验证、实例配置、环境密钥以及任何 Clerk 后端或平台 API 调用。当用户提到 Clerk 管理任务时使用,例如用户列表、创建用户、更新组织、拉取配置等。优先使用 CLI 而非原始 HTTP。

Clerk CLI 操作指南 是什么?

该技能作为 Clerk CLI 的权威指南,专为 AI 编码代理(如 Claude Code、Cursor、Codex)设计。它使代理能够通过 `clerk` 二进制文件无缝执行 Clerk 管理任务,涵盖身份验证(`clerk auth login`)、用户和组织管理(`clerk api /users`)、项目链接(`clerk link`)、环境密钥拉取(`clerk env pull`)、实例配置管理(`clerk config`)以及部署验证(`clerk deploy`)。 技能明确指出代理沙箱环境的局限性,例如系统密钥链和本地主机回调被阻止,并提供了明确的指导:在主机 shell 上运行关键命令,并信任 `clerk doctor --json` 发出的“仅主机”警告。它强调动态端点发现(`clerk api ls`)而非硬编码路径,支持所有主要包管理器(Bun、npm、pnpm、Yarn),并强制执行安全实践,例如使用 `--dry-run` 预览所有变更操作。通过指导将大型响应保存到文件并使用 `jq` 或 Python/Node 进行查询,帮助用户避免上下文窗口过载。最终,该技能确保代理能够可靠、安全地管理 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 后端 API 和平台 API,同时还提供项目级工具(身份验证、链接、环境变量拉取、实例配置)。当用户提及任何与 Clerk 资源相关的内容时,请优先使用 clerk,而不是手动编写 curl。

此技能针对 clerk 的 latest 版本。如果 clerk --version 显示的版本与最新的可用 CLI 版本不一致,请使用 clerk skill install 或 bunx clerk@latest 等包运行器进行刷新。二进制文件始终是事实来源,因此请运行 clerk <command> --help 来验证此技能声称的任何内容。

执行环境(优先使用主机,理解沙箱警告)

大多数 AI 编码代理默认在沙箱中运行 shell 命令,在该沙箱中,用户的主目录、操作系统密钥链、浏览器启动、本地主机回调绑定或网络访问可能被阻止。Clerk CLI 依赖于所有这些主机功能:

  • 操作系统凭据存储:clerk auth login 将 OAuth 令牌存储在系统密钥链中。没有密钥链访问权限的沙箱即使主机已通过身份验证,也会报告“未登录”。
  • 主目录 Clerk 状态:保存的配置、缓存的元数据和备用凭据存储在用户的 Clerk 配置/数据目录下。
  • 链接的项目元数据:从仓库的 git 远程和 Clerk 配置解析。剥离了仓库状态或阻止了主目录读取的沙箱可能会误报“未链接”。
  • 本地 .env* 文件:由 clerk env pull 物化的可发布和密钥。
  • 到 Clerk 的出站网络访问:每个后端和平台 API 调用。
  • 浏览器 + 本地主机 OAuth 回调:clerk auth login 需要这两者。

在代理模式下,CLI 现在会在主机敏感库的边界进行尽力而为的一次性警告检查。当它检测到仅主机的 Clerk 状态或系统功能不可用时,它会发出:

仅主机的 Clerk 状态或系统功能在代理模式下可能不可用。这可能是在沙箱中运行。
在信任身份验证、链接、环境变量或 API 失败之前,请在主机 shell 上重新运行此命令。

将该警告视为权威。命令可能会继续执行,但来自该调用的任何身份验证、链接、环境变量、配置、API、浏览器或 OAuth 回调失败都是不可信的,除非你在主机上重新运行相同的命令。

以下命令优先在用户的主机 shell 上运行,而不是在沙箱中:

clerk doctor, clerk whoami, clerk auth login, clerk link, clerk env pull, clerk apps ..., clerk config ..., clerk api ...。

如果命令意外在沙箱中运行并报告未登录、需要身份验证、未链接、缺少环境变量、密钥链/文件权限错误或网络故障,请不要将结果视为权威。在根据该结果采取行动或向用户报告之前,请在主机上重新运行它。

调用 CLI

在运行任何 clerk 命令之前,请确定要调用的二进制文件,并在整个会话中固定该选择:

# 1. 当全局安装的二进制文件与技能的目标版本匹配时,优先使用它。
command -v clerk >/dev/null 2>&1 && clerk --version

如果打印出 latest 或你信任的任何版本,则在整个会话中用 bare 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 的主机端配置/凭据目录不可写时发出警告,这是当前调用可能处于沙箱中的典型信号。

每个结果都有 name、status(pass/warn/fail)、message、可选的 detail、可选的 remedy(如何修复)以及可选的 fix(自动修复问题的标签)。解析它并根据它采取行动,或将其呈现给用户。如果 主机执行 发出警告,请在信任来自同一沙箱运行的任何身份验证/链接/环境变量/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 模板、webhooksclerk 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 调用。它会自动解析密钥,根据请求体的存在自动检测 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

# 平台 API(帐户级别,非租户数据)
clerk api /v1/platform/applications --platform

对于实例配置,优先使用专用的 clerk config ... 命令,而不是原始平台 API 的 /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 请求返回的负载可能达到数 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 浏览器登录(存储令牌)。代理模式:如果已登录则无操作。如果没有存储的会话,它仍会打开浏览器并绑定本地主机回调,因此它不是无人值守的;对于无头流程,首选 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

相关技能