name: clerk-cli
description: 操作 Clerk CLI（`clerk` 二进制文件）进行认证、用户/组织/会话管理、部署验证、实例配置、环境密钥以及任何 Clerk 后端或平台 API 调用。当用户提及 Clerk 管理任务如“列出 Clerk 用户”、“创建 Clerk 用户”、“更新组织”、“拉取 Clerk 配置”、“clerk env pull”、“clerk doctor”、“clerk deploy”、“clerk deploy status”、“clerk api”或任何一次性 Clerk API 请求时使用。优先使用 CLI 而非原始 HTTP：它自动处理认证、密钥解析、应用/实例定位和格式化。
license: MIT

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 令牌存储在系统密钥链中。没有密钥链访问权限的沙箱会报告 "not logged in"，即使主机已认证。
• 主目录中的 Clerk 状态：保存的配置、缓存的元数据和回退凭据位于用户的 Clerk 配置/数据目录下。
• 关联的项目元数据：从仓库的 git 远程和 Clerk 配置解析。如果沙箱剥离了仓库状态或阻止读取主目录，可能会错误报告 "not linked"。
• **本地 .env* 文件**：由 clerk env pull 生成的公开密钥和秘密密钥。
• 向外的网络访问到 Clerk：每个后端和平台 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 逻辑匹配，该逻辑优先选择与项目锁文件匹配的运行器）：

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 link “关联”到应用。一旦关联，大多数命令会自动从仓库的 git 远程中解析目标应用和开发实例。要定位其他目标，请传递 --app <id> 和/或 --instance dev|prod|<instance_id>。请参阅 [references/auth.md](references/auth.md) 以获取完整的解析顺序。

发现端点 - 不要记忆它们

CLI 附带了 Clerk OpenAPI 目录。请始终动态发现端点，而不是猜测路径：

clerk api ls                  # 列出每个后端 API 端点
clerk api ls users            # 按关键字过滤（匹配路径、摘要、标签、操作 ID）
clerk api ls --platform apps  # 列出平台 API 端点

在 clerk api <path> 之前使用此命令。如果看不到预期的端点，则可能未公开。

clerk api 命令（主力）

clerk api 发出经过身份验证的 HTTP 调用。它会自动解析密钥，根据请求体自动检测方法，支持 stdin，并且可以通过 --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

# 从文件或 stdin 读取请求体
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 ... 命令，而不是原始的 Platform API /config 路径。它们比原始端点形式更干净地处理 dry-run、差异比较和确认。

始终对变更使用 --dry-run，然后再实际运行。 然后在不加 --dry-run 的情况下重新运行（如果确定，可添加 --yes）。在代理模式下，交互式确认被绕过，因此 --dry-run 是破坏性调用的唯一安全网。

JSON 请求体必须是有效的 JSON。 CLI 会验证并拒绝格式错误的负载。

端点路径可以带或不带 /v1/ 前缀 - 对于后端 API 调用，两者都有效。CLI 会自动规范化。

请参阅 [references/recipes.md](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 <command> --help 是标志的权威来源。 此表格是提示，而非规范。在运行不熟悉的命令或标志组合之前，每个会话运行一次 clerk <command> --help。每个命令还在源代码中定义了 setExamples([...])，--help 会将其呈现为可复制粘贴的示例块，因此你几乎不需要猜测语法。

代理模式行为（重要）

CLI 在 stdout 不是 TTY 时自动检测代理模式，或者设置了 --mode agent / CLERK_MODE=agent。在代理模式下：

• 交互式提示被禁用。 通常显示选择器的命令（不带 --app 的 link、不带 --yes 的 unlink、不带子命令的 users）要么自动解析，要么退出并显示用法错误。不带参数的 clerk api 会打印使用指南并退出 0；请显式传递端点（或 ls）。在脚本化调用中始终传递显式标志（--app、--yes）。
• 主机敏感操作每次调用都会发出一次沙箱警告。 主目录中的 Clerk 状态、密钥链访问、网络化的 Clerk 调用、浏览器启动和本地主机 OAuth 回调设置都可能触发上述警告。如果出现，请在信任结果之前在主机上重新运行相同的命令。
• 如果你的 harness 没有明确呈现为代理模式，请强制设置。 当你希望 CLI 的非交互行为及沙箱警告路径确定性地适用时，请使用 --mode agent 或 CLERK_MODE=agent。
• link 支持确定性代理流程。 在代理模式下，clerk link --app <id> 直接关联。没有 --app 时，CLI 会先尝试静默的基于密钥的自动关联；如果无法明确确定应用，则退出并告诉你传递 --app。
• 在代理模式下，除非已认证或给定了目标，否则 init 不会为你选择或创建真实的 Clerk 应用。 传递 --app <id>（或预先关联项目）以认证并关联真实应用，或者传递 --keyless 以在支持无密钥功能的框架上引导新项目时使用自动生成的临时开发密钥。如果没有这两者，代理模式会打印手动设置指南并干净退出。
• 在代理模式下，unlink 需要 --yes。 这与其他破坏性命令保持了相同的安全门槛，同时仍然允许代理以非交互方式完成取消关联。
• 变更仍然需要 --yes，除非你接受每次调用的确认是不可能的。
• 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](references/agent-mode.md#deploy-handoff-and-verification)。
• --input-json <json|@file|-> 将 JSON 展开为任何命令上的标志（例如 clerk init --input-json '{"framework":"next","yes":true}'）。也接受管道 stdin：echo '{"yes":true}' | clerk init。将 --input-json 放在叶子子命令之后。完整规则请参阅 [references/agent-mode.md](references/agent-mode.md#passing-options-as-json---input-json)。

完整的矩阵和沙箱详细信息请参阅 [references/agent-mode.md](references/agent-mode.md)。

输出格式和错误

• JSON 输出： apps list 和 doctor 上的 --json。对于 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（应被 git 忽略）。不要将秘密密钥粘贴到代码或聊天中。
5. 使用 doctor --json 在假设 CLI 损坏之前进行诊断。

参考资料

• [references/auth.md](references/auth.md) - 认证流程、密钥解析顺序、主机与沙箱行为、--app/--instance 定位、后端与平台 API。
• [references/recipes.md](references/recipes.md) - 常见 Clerk 任务的可复制粘贴配方。
• [references/agent-mode.md](references/agent-mode.md) - 代理模式行为矩阵、沙箱警告语义、退出码、错误格式。