Back to Details

clerk-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clerk CLI

Clerk CLI

The 
clerk
binary is a pre-authenticated gateway to Clerk's Backend API and Platform API, plus project-level tooling (auth, linking, env pulls, instance config). When the user asks anything that touches a Clerk resource, reach for 
clerk
first instead of hand-rolling 
curl
.
This skill targets clerk 
latest
. If 
clerk --version
disagrees with the latest available CLI, refresh it with 
clerk skill install
or a package runner such as 
bunx clerk@latest
. The binary is always the source of truth, so run 
clerk <command> --help
to verify anything this skill claims.
clerk
二进制文件是接入Clerk后端API和平台API的预认证网关，同时提供项目级工具（身份验证、链接、环境密钥拉取、实例配置等功能）。当用户需要操作任何Clerk资源时，优先使用
clerk
命令，而非手动编写
curl
请求。
本技能针对Clerk 
latest
版本。如果
clerk --version
显示的版本与最新可用CLI版本不符，请使用
clerk skill install
或包运行器（如
bunx clerk@latest
）更新。二进制文件始终是权威来源，因此可运行
clerk <command> --help
来验证本技能中的任何说明。

Execution environment (prefer the host, understand the sandbox warning)

执行环境（优先使用主机环境，了解沙箱警告）

Most AI coding agents default to running shell commands in a sandbox where the user's home directory, OS keychain, browser launch, localhost callback binding, or network access may be blocked. The Clerk CLI depends on all of those host capabilities:
  • OS credential store: 
    clerk auth login
    stores the OAuth token in the system keychain. A sandbox without keychain access reports "not logged in" even when the host is authenticated.
  • Home-directory Clerk state: saved config, cached metadata, and fallback credentials live under the user's Clerk config/data directories.
  • Linked project metadata: resolved from the repo's git remote plus Clerk config. Sandboxes with stripped repo state or blocked home-dir reads can misreport "not linked".
  • Local 
    .env*
    files    : publishable and secret keys materialized by 
    clerk env pull
    .
  • Outbound network access to Clerk: every Backend and Platform API call.
  • Browser + localhost OAuth callback: 
    clerk auth login
    needs both.
In agent mode, the CLI now does a best-effort warn-once check at the host-sensitive library boundaries. When it detects that host-only Clerk state or system capabilities are unavailable, it emits:
text
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.
Treat that warning as authoritative. The command may continue, but any auth, link, env, config, API, browser, or OAuth callback failure from that invocation is untrusted until you rerun the same command on the host.
Prefer these commands on the user's host shell, not in a sandbox:
clerk doctor
, 
clerk whoami
, 
clerk auth login
, 
clerk link
, 
clerk env pull
, 
clerk apps ...
, 
clerk config ...
, 
clerk api ...
.
If a command was accidentally run in a sandbox and it reports 
Not logged in
, 
auth_required
, 
not linked
, missing env, keychain/file permission errors, or network failures, do not treat the result as authoritative. Rerun it on the host before acting on it or reporting it to the user.
大多数AI编码代理默认在沙箱中运行shell命令，而沙箱可能会限制用户的主目录、OS密钥链、浏览器启动、本地主机回调绑定或网络访问。Clerk CLI依赖所有这些主机功能：
  • OS凭证存储：
    clerk auth login
    会将OAuth令牌存储在系统密钥链中。如果沙箱没有密钥链访问权限，即使主机已认证，也会显示“未登录”。
  • 主目录中的Clerk状态：已保存的配置、缓存的元数据和备用凭证存储在用户的Clerk配置/数据目录下。
  • 关联项目元数据：从仓库的git远程地址和Clerk配置解析而来。如果沙箱中的仓库状态被剥离或主目录读取被阻止，可能会错误报告“未关联”。
  • 本地
    .env*
    文件    ：
    clerk env pull
    生成的可发布密钥和密钥材料。
  • 访问Clerk的出站网络：所有后端和平台API调用都需要。
  • 浏览器+本地主机OAuth回调：
    clerk auth login
    需要这两者。
在代理模式下，CLI现在会在主机敏感库边界处进行一次性的尽力检查。当检测到仅主机可用的Clerk状态或系统功能不可用时，会输出：
text
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
、缺少环境变量、密钥链/文件权限错误或网络故障，请勿将结果视为权威。在采取行动或向用户报告之前，先在主机上重新运行该命令。

Invoking the CLI

调用CLI

Before running any 
clerk
command, figure out which binary to invoke and bind that choice for the rest of the session:
sh
undefined
在运行任何
clerk
命令之前，确定要调用的二进制文件，并在整个会话中保持该选择：
sh
undefined

1. Prefer a globally installed binary when it matches the skill's target version.

1. 当全局安装的二进制文件与技能目标版本匹配时，优先使用它。

command -v clerk >/dev/null 2>&1 && clerk --version

If that prints `latest` or any version you trust, use bare `clerk` for the rest of the session.

Otherwise fall back to a package runner, in this order (matches the CLI's own `preferredRunner` logic, which prefers the runner that matches the project's lockfile):

| Project package manager   | Invocation                       |
| ------------------------- | -------------------------------- |
| 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) has no `dlx`; treat those projects as "no preferred runner" and fall back to the first runner from the list above that's on PATH.

The published npm package is **`clerk`**, not `@clerk/cli`. Never teach `npm install -g clerk` as the primary path. If the global CLI is stale or behaves differently from this skill, either upgrade the global install or fall back to the `latest` runner form above.
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`运行器形式。

Prerequisites (run at session start)

前置条件（会话开始时运行）

Before running any other Clerk command in a session, verify the CLI is authenticated, linked, and healthy:
sh
clerk --version               # confirm the binary is on PATH
clerk doctor --json           # structured health check; exit 1 if anything failed
Always run 
clerk doctor --json
first. It catches the common setup failures (not logged in, project not linked, missing keys, stale CLI version) up front, so later commands don't fail with confusing errors. In agent mode it also includes a 
Host execution
check that warns when Clerk's host-side config / credential directories are not writable, which is the canonical signal that the current invocation is likely sandboxed.
Each result has 
name
, 
status
(
pass
/
warn
/
fail
), 
message
, optional 
detail
, optional 
remedy
(how to fix it), and optional 
fix
(label for auto-fixable issues). Parse that and act on it, or surface it to the user. If 
Host execution
warns, rerun the command on the host before trusting any auth/link/env/API failures from the same sandboxed run. Rerun 
clerk doctor --json
whenever a later command starts misbehaving.
If 
clerk --version
reports a newer CLI than this skill covers, trust 
clerk <command> --help
first and refresh this skill bundle from its source.
在会话中运行任何其他Clerk命令之前，验证CLI已认证、已关联且运行正常：
sh
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
的内容，并从源更新本技能包。

The mental model

思维模型

LayerWhat it doesCommands
Session / projectAuth, link a repo to a Clerk app, pull env keys
auth login
, 
link
, 
unlink
, 
whoami
, 
env pull
, 
doctor
Instance configManage the configuration (social providers, session lifetimes, etc.) for a specific instance
config pull
, 
config schema
, 
config patch
, 
config put
Backend API (default)Runtime data: users, orgs, sessions, invitations, JWT templates, webhooks
clerk api <path>
Platform API (
--platform
)		Account-level: applications, instances, billing
clerk api --platform <path>
A project is "linked" to an application via 
clerk link
. Once linked, most commands auto-resolve the target app and dev instance from the repo's git remote. To target something else, pass 
--app <id>
and/or 
--instance dev|prod|<instance_id>
. See references/auth.md for the full resolution order.
层级功能描述命令
会话/项目身份验证、将仓库关联到Clerk应用、拉取环境密钥
auth login
, 
link
, 
unlink
, 
whoami
, 
env pull
, 
doctor
实例配置管理特定实例的配置（社交提供商、会话生命周期等）
config pull
, 
config schema
, 
config patch
, 
config put
后端API（默认）运行时数据：用户、组织、会话、邀请、JWT模板、Webhook
clerk api <path>
平台API（
--platform
）		账户级：应用、实例、账单
clerk api --platform <path>
通过
clerk link
将项目“关联”到应用。关联后，大多数命令会自动从仓库的git远程地址解析目标应用和开发实例。要定位其他资源，请传递
--app <id>
和/或
--instance dev|prod|<instance_id>
。有关完整的解析顺序，请参阅references/auth.md。

Discover endpoints - don't memorize them

发现端点 - 无需记忆

The CLI ships with the Clerk OpenAPI catalog. Always discover endpoints dynamically instead of guessing paths:
sh
clerk api ls                  # list every Backend API endpoint
clerk api ls users            # filter by keyword (matches path, summary, tag, operationId)
clerk api ls --platform apps  # list Platform API endpoints
Use this before 
clerk api <path>
. If you don't see the endpoint you expected, it probably isn't exposed.
CLI附带Clerk OpenAPI目录。始终动态发现端点，而非猜测路径：
sh
clerk api ls                  # 列出所有后端API端点
clerk api ls users            # 按关键字过滤（匹配路径、摘要、标签、operationId）
clerk api ls --platform apps  # 列出平台API端点
在运行
clerk api <path>
之前使用此命令。如果未找到预期的端点，可能它并未暴露。

The 
clerk api
command (the workhorse)

clerk api
命令（核心工具）

clerk api
makes authenticated HTTP calls. It auto-resolves keys, auto-detects method from body presence, supports stdin, and can preview mutations with 
--dry-run
.
sh
undefined
clerk api
用于发起已认证的HTTP调用。它会自动解析密钥、根据是否存在请求体自动检测方法、支持标准输入，并且可以使用
--dry-run
预览变更。
sh
undefined

GET requests

GET请求

clerk api /users # list users clerk api /users/user_abc123 # fetch one clerk api /users?limit=5&order_by=-created_at # query params work inline
clerk api /users # 列出用户 clerk api /users/user_abc123 # 获取单个用户 clerk api /users?limit=5&order_by=-created_at # 查询参数可直接内联

Mutating requests

变更请求

clerk api /users -d '{"email_address":["a@b.co"]}' # POST (auto-detected from body) clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}' clerk api /users/user_abc123 -X DELETE
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

Body from file or stdin

从文件或标准输入读取请求体

clerk api /users --file payload.json cat payload.json | clerk api /users
clerk api /users --file payload.json cat payload.json | clerk api /users

Always preview mutations first

始终先预览变更

clerk api /users/user_abc123 -X DELETE --dry-run clerk api /users/user_abc123 -X DELETE --yes # skip confirmation once you've verified
clerk api /users/user_abc123 -X DELETE --dry-run clerk api /users/user_abc123 -X DELETE --yes # 验证后跳过确认

Target a specific app/instance

定位特定应用/实例

clerk api /users --app app_abc123 --instance prod
clerk api /users --app app_abc123 --instance prod

Include response headers when debugging

调试时包含响应头

clerk api /users --include
clerk api /users --include

Platform API (account-level, not tenant data)

平台API（账户级，非租户数据）

clerk api /v1/platform/applications --platform

For instance config, prefer the dedicated `clerk config ...` commands over raw Platform API `/config` paths. They handle dry-run, diffing, and confirmation more cleanly than the raw endpoint form.

**Always `--dry-run` a mutation before running it for real.** Then re-run without `--dry-run` (add `--yes` if you're sure). In agent mode, interactive confirmation is bypassed, so `--dry-run` is the only safety net for destructive calls.

**JSON bodies must be valid JSON.** The CLI validates and rejects malformed payloads.

**Endpoint paths may be given with or without `/v1/` prefix** - both work for Backend API calls. The CLI normalizes.

See [references/recipes.md](references/recipes.md) for concrete patterns: listing/filtering users, creating orgs, impersonation sessions, etc.
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](references/recipes.md)：列出/过滤用户、创建组织、模拟会话等。

Inspecting large outputs (do not flood your context)

检查大型输出（避免占用过多上下文）

users list
, 
apps list
, 
config pull
, and most 
clerk api
GETs return payloads that can be many kilobytes or megabytes. Production tenants commonly have thousands of users; an instance config can be hundreds of fields deep. Reading those responses into the conversation costs context window for no benefit. Save the response to a file first, then query just what you need with 
jq
:
sh
undefined
users list
、
apps list
、
config pull
以及大多数
clerk api
的GET请求返回的负载可能有数千字节甚至数兆字节。生产租户通常有成千上万的用户；实例配置可能包含数百个字段。将这些响应读取到对话中会浪费上下文窗口资源且无益处。先将响应保存到文件，然后使用
jq
仅查询所需内容：
sh
undefined

1. Persist the response. Use --limit 250 to maximize page size for users list.

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
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. Inspect only what you need.

2. 仅检查所需内容。

jq '.data | length' /tmp/users.json # current page size jq '.hasMore' /tmp/users.json # are more pages available? jq '.data[0] | keys' /tmp/users.json # discover the user shape once jq '.data[] | {id, email_addresses}' /tmp/users.json # project to a few fields jq '[.data[] | select(.banned)] | length' /tmp/users.json # aggregate without reading rows

**If `jq` is not available**, fall back to Python or Node - both can stream the file without printing it whole:

```sh
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
the file only when you genuinely need to see the raw structure for one-off debugging. When walking pages, write each page to its own file (e.g. 
page-${offset}.json
) so individual pages stay independently inspectable.
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 - 两者都可以流式处理文件而无需完整打印：

```sh
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
），以便单独检查每个页面。

Core commands at a glance

核心命令概览

CommandPurposeKey flags
clerk init
Scaffold Clerk into a project. 
--starter
only supports bootstrap for Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue, and JavaScript.
--framework
, 
--pm
, 
--name
(with 
--starter
), 
--app
, 
--starter
, 
-y
, 
--no-skills
clerk auth login
OAuth browser login (stores token). Agent mode: no-op if already logged in. With no stored session it still opens a browser and binds a localhost callback, so it is not unattended; prefer 
CLERK_PLATFORM_API_KEY
for headless flows. Aliases: 
signup
, 
signin
, 
sign-in
. Top-level shortcut: 
clerk login
.		-
clerk auth logout
Clear stored credentials. Aliases: 
signout
, 
sign-out
. Top-level shortcut: 
clerk logout
.		-
clerk whoami
Print the logged-in email.-
clerk link
/ 
clerk unlink
Link this repo to a Clerk app, or remove the link. 
unlink
requires 
--yes
in agent mode.		(see 
--help
)
clerk env pull
Write publishable + secret keys to the framework's env file (merge, not clobber). Resolves 
.env.development.local
→ framework-preferred file → 
.env.local
; override with 
--file
.		(see 
--help
)
clerk config {pull,schema}
Fetch instance config JSON, or its JSON Schema.(see 
--help
)
clerk config patch
Partial update (PATCH) of instance config. Pass 
--destructive
to actually delete sub-resources touched by the patch rather than resetting them to defaults.
--app
, 
--instance
, 
--file
, 
--json
, 
--dry-run
, 
--yes
, 
--destructive
clerk config put
Full replacement (PUT) of instance config. Pass 
--destructive
to actually delete removed sub-resources rather than resetting them to defaults.
--app
, 
--instance
, 
--file
, 
--json
, 
--dry-run
, 
--yes
, 
--destructive
clerk apps {list,create}
List or create Clerk applications. Defaults to JSON in agent mode.(see 
--help
)
clerk users
(no subcommand)		Interactive picker for 
users
actions in human mode; in agent mode prints the action list and exits 
2
. Always pass an explicit subcommand from agents.
--app
, 
--instance
, 
--secret-key
clerk users list
List users via curated BAPI flags. JSON output (default when piped or in agent mode) is 
{data, hasMore}
so callers can paginate without 
/users/count
. 
--limit
defaults to 100 (max 250).
--limit
, 
--offset
, 
--query
, 
--email-address
, 
--phone-number
, 
--username
, 
--user-id
, 
--external-id
, 
--order-by
, 
--json
, 
--app
, 
--instance
, 
--secret-key
clerk users create
Create a user from curated flags or a raw BAPI body. Confirmation prompt unless 
--yes
.
--email
, 
--phone
, 
--username
, 
--password
, 
--first-name
, 
--last-name
, 
--external-id
, 
-d, --data
, 
--file
, 
--dry-run
, 
--yes
, 
--json
clerk users open [user-id]
Open a user's dashboard page. Agent mode requires 
user-id
and prints a JSON descriptor instead of launching a browser.		(see 
--help
)
clerk open [subpath]
Open the linked app's dashboard in a browser. Agent mode: prints a JSON descriptor instead of opening.(see 
--help
)
clerk deploy
Human-mode production deploy wizard. Agent mode: emits a read-only JSON handoff and tells the agent whether to ask the human to run the wizard, wait for provisioning, finish OAuth, or do nothing.
--mode agent
, 
--mode human
, 
--verbose
clerk deploy status
Read-only deploy verification. Triggers a DNS check, reports aggregate domain and OAuth readiness, and exits 
0
only when complete. Agent mode does one quick check by default; pass 
--wait
to keep waiting.
--mode agent
, 
--wait
, 
--verbose
clerk doctor
Health check (CLI version, login, link, env, config, completion; plus host-execution probe in agent mode).
--json
, 
--spotlight
, 
--verbose
, 
--fix
clerk api [path]
Authenticated HTTP to Backend/Platform API.
-X
, 
-d
, 
--file
, 
--dry-run
, 
--yes
, 
--include
, 
--app
, 
--secret-key
, 
--instance
, 
--platform
clerk api ls [filter]
Discover endpoints from the bundled OpenAPI catalog.(see 
--help
)
clerk completion [shell]
Print a shell completion script (
bash
, 
zsh
, 
fish
, 
powershell
).		-
clerk update
Update the CLI to the latest version.
--channel
, 
-y
, 
--all
clerk skill install
Reinstall the bundled 
clerk-cli
skill from the CLI. In this standalone bundle, update the skill source directly instead.		(see 
--help
)
clerk <command> --help
is the source of truth for flags. This table is a hint, not a spec. Before running an unfamiliar command or flag combination, run 
clerk <command> --help
once per session. Every command also defines 
setExamples([...])
in source, which 
--help
renders as a copy-pasteable Examples block, so you rarely need to guess syntax.
命令用途关键标志
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
打印登录邮箱。-
clerk link
/ 
clerk unlink
将此仓库关联到Clerk应用，或移除关联。代理模式下
unlink
需要
--yes
。		(查看
--help
)
clerk env pull
将可发布密钥+密钥写入框架的环境文件（合并而非覆盖）。解析顺序为
.env.development.local
→ 框架首选文件 → 
.env.local
；可使用
--file
覆盖。		(查看
--help
)
clerk config {pull,schema}
获取实例配置JSON，或其JSON Schema。(查看
--help
)
clerk config patch
实例配置的部分更新（PATCH）。传递
--destructive
以实际删除补丁涉及的子资源，而非将其重置为默认值。
--app
, 
--instance
, 
--file
, 
--json
, 
--dry-run
, 
--yes
, 
--destructive
clerk config put
实例配置的完全替换（PUT）。传递
--destructive
以实际删除已移除的子资源，而非将其重置为默认值。
--app
, 
--instance
, 
--file
, 
--json
, 
--dry-run
, 
--yes
, 
--destructive
clerk apps {list,create}
列出或创建Clerk应用。代理模式下默认为JSON输出。(查看
--help
)
clerk users
（无子命令）		人机模式下
users
操作的交互式选择器；代理模式下打印操作列表并以退出码
2
退出。代理必须始终传递明确的子命令。
--app
, 
--instance
, 
--secret-key
clerk users list
通过精选的BAPI标志列出用户。JSON输出（管道传输或代理模式下默认）格式为
{data, hasMore}
，因此调用者无需使用
/users/count
即可分页。
--limit
默认值为100（最大值250）。
--limit
, 
--offset
, 
--query
, 
--email-address
, 
--phone-number
, 
--username
, 
--user-id
, 
--external-id
, 
--order-by
, 
--json
, 
--app
, 
--instance
, 
--secret-key
clerk users create
通过精选标志或原始BAPI请求体创建用户。除非使用
--yes
，否则会显示确认提示。
--email
, 
--phone
, 
--username
, 
--password
, 
--first-name
, 
--last-name
, 
--external-id
, 
-d, --data
, 
--file
, 
--dry-run
, 
--yes
, 
--json
clerk users open [user-id]
打开用户的仪表板页面。代理模式下需要
user-id
，并打印JSON描述符而非启动浏览器。		(查看
--help
)
clerk open [subpath]
在浏览器中打开关联应用的仪表板。代理模式下：打印JSON描述符而非打开浏览器。(查看
--help
)
clerk deploy
人机模式下的生产部署向导。代理模式下：输出只读JSON交接信息，并告知代理是否需要让用户运行向导、等待配置完成、完成OAuth或不执行任何操作。
--mode agent
, 
--mode human
, 
--verbose
clerk deploy status
只读部署验证。触发DNS检查，报告域名和OAuth就绪状态汇总，仅当完成时退出码为
0
。代理模式下默认进行一次快速检查；传递
--wait
可持续等待。
--mode agent
, 
--wait
, 
--verbose
clerk doctor
健康检查（CLI版本、登录状态、关联状态、环境变量、配置、自动补全；代理模式下还包括主机执行探测）。
--json
, 
--spotlight
, 
--verbose
, 
--fix
clerk api [path]
向后端/平台API发起已认证的HTTP请求。
-X
, 
-d
, 
--file
, 
--dry-run
, 
--yes
, 
--include
, 
--app
, 
--secret-key
, 
--instance
, 
--platform
clerk api ls [filter]
从内置OpenAPI目录发现端点。(查看
--help
)
clerk completion [shell]
打印shell自动补全脚本（
bash
, 
zsh
, 
fish
, 
powershell
）。		-
clerk update
将CLI更新到最新版本。
--channel
, 
-y
, 
--all
clerk skill install
从CLI重新安装内置的
clerk-cli
技能。在独立包中，请直接从源更新技能。		(查看
--help
)
clerk <command> --help
是标志的权威来源。此表格仅为提示，而非规范。在运行不熟悉的命令或标志组合之前，每个会话中运行一次
clerk <command> --help
。每个命令还在源代码中定义了
setExamples([...])
，
--help
会将其渲染为可复制粘贴的示例块，因此你几乎无需猜测语法。

Agent-mode behavior (important)

代理模式行为（重要）

The CLI auto-detects agent mode when stdout is not a TTY, or when 
--mode agent
/ 
CLERK_MODE=agent
is set. In agent mode:
  • Interactive prompts are disabled. Commands that would normally show pickers (
    link
    without 
    --app
    , 
    unlink
    without 
    --yes
    , 
    users
    without a subcommand) either auto-resolve or exit with a usage error. 
    clerk api
    with no args prints usage guidance and exits 0; pass an endpoint (or 
    ls
    ) explicitly. Always pass explicit flags (
    --app
    , 
    --yes
    ) in scripted calls.
  • Host-sensitive operations emit a sandbox warning once per invocation. Home-directory Clerk state, keychain access, networked Clerk calls, browser launch, and localhost OAuth callback setup can trigger the warning shown above. If it appears, rerun the same command on the host before trusting the result.
  • If your harness does not clearly present as agent mode, force it. Use 
    --mode agent
    or 
    CLERK_MODE=agent
    when you want the CLI's non-interactive behavior and sandbox warning path to apply deterministically.
  • link
    supports deterministic agent flows.     In agent mode, 
    clerk link --app <id>
    links directly. Without 
    --app
    , the CLI will try silent key-based autolink first; if it cannot determine the app unambiguously, it exits and tells you to pass 
    --app
    .
  • init
    never selects or creates a real Clerk app for you in agent mode unless authenticated or given a target.     Pass 
    --app <id>
    (or pre-link the project) to authenticate and link a real app, or pass 
    --keyless
    to use auto-generated temporary development keys when bootstrapping a new project on a keyless-capable framework. Without either, agent mode prints manual setup guidance and exits cleanly.
  • unlink
    requires 
    --yes
    in agent mode.     This preserves the same safety bar as other destructive commands while still letting an agent complete the unlink non-interactively.
  • Mutations still require 
    --yes
     unless you accept per-call confirmation is impossible.
  • doctor --fix
    is ignored.     Parse 
    doctor --json
    output's 
    remedy
    field and act on it yourself.
  • apps list
    and 
    apps create
    default to JSON     when piped.
  • users
    defaults to JSON when piped, like 
    apps
    .     
    clerk users list
    and 
    clerk users create
    emit JSON in agent mode. Bare 
    clerk users
    (no subcommand) is a usage error in agent mode - pass 
    list
    , 
    create
    , or 
    open
    explicitly. 
    clerk users open
    requires the 
    user-id
    positional in agent mode and prints a JSON descriptor instead of launching a browser.
  • deploy
    has an agent handoff plus a verification gate.     In agent mode, bare 
    clerk deploy
    is read-only and emits a JSON handoff. It never drives the interactive wizard. Do not tell Claude or another agent to run 
    ! clerk deploy
    , because the wizard needs interactive stdin prompts. Ask the human to run 
    clerk deploy
    in a new terminal window when needed, then run 
    clerk deploy status --mode agent
    to verify completion. See references/agent-mode.md.
  • --input-json <json|@file|->
     expands JSON into flags on any command (e.g. 
    clerk init --input-json '{"framework":"next","yes":true}'
    ). Piped stdin is also accepted: 
    echo '{"yes":true}' | clerk init
    . Place 
    --input-json
    after the leaf subcommand. Full rules in references/agent-mode.md.
Full matrix and sandbox details in references/agent-mode.md.
当stdout不是TTY，或设置了
--mode agent
/
CLERK_MODE=agent
时，CLI会自动检测到代理模式。在代理模式下：
  • 交互式提示被禁用。通常会显示选择器的命令（不带
    --app
    的
    link
    、不带
    --yes
    的
    unlink
    、不带子命令的
    users
    ）要么自动解析，要么退出并显示使用错误。不带参数的
    clerk api
    会打印使用指南并以退出码
    0
    退出；请显式传递端点（或
    ls
    ）。在脚本调用中始终传递明确的标志（
    --app
    , 
    --yes
    ）。
  • 主机敏感操作会在每次调用时发出一次沙箱警告。主目录中的Clerk状态、密钥链访问、Clerk网络调用、浏览器启动和本地主机OAuth回调设置可能会触发上述警告。如果出现警告，在信任结果之前先在主机上重新运行相同命令。
  • 如果你的工具未明确呈现为代理模式，请强制设置。当你需要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
    ，因为向导需要交互式标准输入提示。必要时请用户在新终端窗口中运行
    clerk deploy
    ，然后运行
    clerk deploy status --mode agent
    验证完成。请参阅references/agent-mode.md。
  • --input-json <json|@file|->
     可在任何命令上将JSON扩展为标志（例如
    clerk init --input-json '{"framework":"next","yes":true}'
    ）。也接受管道标准输入：
    echo '{"yes":true}' | clerk init
    。将
    --input-json
    放在叶子子命令之后。完整规则请参阅references/agent-mode.md。
完整的矩阵和沙箱详情请参阅references/agent-mode.md。

Output format and errors

输出格式和错误

  • JSON output: 
    --json
    on 
    apps list
    and 
    doctor
    . For 
    clerk api
    , the response body is the raw API JSON, so pipe into 
    jq
    freely.
  • Exit codes: 
    0
    success, 
    1
    runtime error, 
    2
    usage/validation error. 
    doctor
    returns 
    1
    if any check failed.
  • Error format: User-facing errors print a single line to stderr and set a non-zero exit code. Use 
    --verbose
    for stack traces when debugging.
  • JSON输出：
    apps list
    和
    doctor
    使用
    --json
    标志。对于
    clerk api
    ，响应体是原始API JSON，因此可自由通过管道传输到
    jq
    。
  • 退出码：
    0
    表示成功，
    1
    表示运行时错误，
    2
    表示使用/验证错误。如果任何检查失败，
    doctor
    返回
    1
    。
  • 错误格式：面向用户的错误会向stderr打印单行信息并设置非零退出码。调试时使用
    --verbose
    查看堆栈跟踪。

Safety rules for autonomous use

自主使用的安全规则

  1. Discover before acting: 
    clerk api ls <keyword>
    before 
    clerk api <path>
    .
  2. Preview mutations: 
    --dry-run
    on every 
    config patch
    , 
    config put
    , 
    api -X POST/PATCH/PUT/DELETE
    .
  3. Target explicitly in production: pass 
    --instance prod
    rather than relying on defaults, and confirm with the user before any production mutation.
  4. Never commit secrets: 
    env pull
    writes to 
    .env.local
    (which should be gitignored). Don't paste secret keys into code or chat.
  5. Use 
    doctor --json
     to diagnose before assuming the CLI is broken.
  1. 先发现再行动：运行
    clerk api ls <keyword>
    之后再执行
    clerk api <path>
    。
  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

参考资料

  • references/auth.md - auth flow, key resolution order, host-vs-sandbox behavior, 
    --app
    /
    --instance
    targeting, Backend vs Platform API.
  • references/recipes.md - copy-pasteable recipes for common Clerk tasks.
  • references/agent-mode.md - agent-mode behavior matrix, sandbox warning semantics, exit codes, error format.
  • references/auth.md - 认证流程、密钥解析顺序、主机与沙箱行为、
    --app
    /
    --instance
    定位、后端与平台API对比。
  • references/recipes.md - 常见Clerk任务的可复制粘贴方案。
  • references/agent-mode.md - 代理模式行为矩阵、沙箱警告语义、退出码、错误格式。