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 模板、webhooks | 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 调用。它会自动解析密钥,根据请求体的存在自动检测 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 login | OAuth 浏览器登录(存储令牌)。代理模式:如果已登录则无操作。如果没有存储的会话,它仍会打开浏览器并绑定本地主机回调,因此它不是无人值守的;对于无头流程,首选 CLERK_PLATFORM_API_KEY。别名:signup, signin, sign-in。顶级快捷方式:clerk login。 | - |
clerk auth logout | 清除存储的凭据。别名:signout, sign-out。顶级快捷方式:clerk logout。 | - |
clerk whoami | 打印已登录的电子邮件。 |