# Clerk CLI command catalog

Read this catalog when choosing a command or checking its main flags. It is a hint, not a spec: verify unfamiliar syntax with `clerk <command> --help`.

| Command                       | Purpose                                                                                                                                                                                                                                                                                                             | Key flags                                                                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clerk init`                  | Scaffold Clerk into a project. On a framework with accountless support, an unauthenticated bootstrap with no `--app`, or an unauthenticated agent run with no `--app` or existing link, writes temporary development keys by default — no login required (see [Accountless setup](../SKILL.md#accountless-setup)). `--starter` bootstraps Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue, JavaScript, Expo, and (with Xcode on macOS) iOS and macOS apps. For iOS and macOS, follow the [iOS setup prompt](https://clerk.com/docs/ios/getting-started/quickstart.md): with `--json`, init reports what setup needs as JSON statuses (`input-required`, `application-required`, `setup-interrupted`) instead of prompting. In agent mode, `--app` that would replace an existing application link stops with a usage error unless `--relink` is passed. With `--json`, it also emits an `input-required` status. Inside a Git repository, the link is shared by every project in it. `--accountless` with `--app`/`--login`, and `--template`/`--fresh` with `--login`, are usage errors before anything is scaffolded. `--template`/`--fresh` on a run that *resolves* to a real app (including while merely signed in) errors only after strategy resolution — so a starter run leaves the scaffolded project behind. | `--framework`, `--pm`, `--name` (with `--starter`), `--app`, `--relink`, `--json` (iOS and macOS), `--starter`, `--accountless`, `--login`, `--template`, `--fresh`, `-y`, `--no-skills`                                   |
| `clerk auth login`            | OAuth browser login (stores token). Not required for bootstrap or accountless instance config. Agent mode, already logged in: skips the browser but tries to claim the app behind `.clerk/keyless.json` in the current folder. 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`. `--print` writes `KEY=value` lines to stdout instead, for copying production keys to a host; it fails without printing anything when Clerk returns no secret key. Never read or show its output.                                                                                                                              | `--print` (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 security [audit]`      | Grade the instance against Clerk's security recommendations. Informational: exits `0` whatever the grade; gate on `score.hasCriticalGap`. JSON in agent mode, with a `patch` (a `config patch` body) per fixable finding and a `customFlows` note on fixes that change sign-in or sign-up flows. Needs an account: an accountless app exits `auth_required`. | `--app`, `--instance`, `--json` |
| `clerk security fix [ids...]` | Apply one combined config patch for the named ids, or `--all` (unmet critical and recommended checks with an inline patch, plus what they unlock). `mfa` needs `--factors` and `passwordless-auth` needs `--strategy`; `--all` skips both unless those flags are passed. Agent mode requires ids or `--all`, and `--yes` unless `--dry-run`. | `--all`, `--good-to-have`, `--factors`, `--strategy`, `--dry-run`, `--yes`, `--json` |
| `clerk security checks`       | List the check catalog offline, with ids and severities. No auth.                                                                                                                                                                                                                                                   | `--json` |
| `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. **No confirmation prompt in any mode** - it writes immediately. `--yes` is accepted but has no effect. `--dry-run` is the only safety net; preview with it first.                                                                                                                                                                                                                            | `--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 impersonate [user]`    | Sign in as a user for debugging: creates a short-lived actor token and prints the sign-in URL. Alias: `clerk imp`. Requires `clerk auth login` (no `--secret-key`-only bypass) — every token is stamped `cli:<email>` for auditability. `[user]` accepts a `user_...` ID, exact email, or fuzzy search term. On production it bypasses the user's MFA and may count against the impersonation quota — confirm with the user first. | `--print`, `--open`, `--yes`, `--expires-in <seconds>` (default 3600), `--actor <context>`, `--app`, `--instance`                                                                |
| `clerk impersonate revoke <actor-token-id>` | Revoke a pending actor token. The token `id` is printed only at creation (the Backend API has no actor-token list endpoint), so capture it then.                                                                                                                                                      | `--app`, `--instance`                                                                                                                                                            |
| `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: without `--domain`, only prints the deploy report; with `--domain <domain>`, creates the production instance (or resumes the existing one on that domain) without prompting, then prints the report. Its `nextAction` says what to do next: add DNS records, save OAuth credentials from `oauth.setup`, wait, or copy the production keys to the host (see [Copy the production keys to the host](agent-mode.md#copy-the-production-keys-to-the-host)).                                                                                                                 | `--domain`, `--yes` (wizard only), `--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 webhooks listen`       | First-party local webhook tunnel (like `stripe listen`): opens a Svix relay inbox URL and forwards each delivery to your local handler. No auth, no linked project, no Clerk API. Full flow in [recipes.md](recipes.md#webhooks-local-testing).                                                 | `--forward-to <url>` (required), `--token <c_token>`, `-H, --header <k:v>` (repeatable), `--json` (NDJSON)                                                                       |
| `clerk webhooks token`        | Mint a relay token (`c_` + 10 base62 chars) to pin a stable `listen` inbox URL across machines: `clerk webhooks listen --token "$(clerk webhooks token)" --forward-to ...`.                                                                                                                                          | `--json`                                                                                                                                                                         |
| `clerk webhooks verify`       | Verify a webhook signature offline (pure local HMAC, no auth): from a saved `listen` event line (`--delivery @event.json`) or from the four raw values.                                                                                                                                                             | `--secret <whsec>` (required), `--delivery @file`, `--payload @file`, `--id`, `--timestamp`, `--signature`, `--json`                                                             |
| `clerk enable orgs` / `clerk disable orgs` | Toggle Organizations on the instance. For org features, components, and API usage, see the `clerk-orgs` skill.                                                                                                                                                                                         | `--force-selection`, `--auto-create`, `--max-members <n>`, `--domains`, `--dry-run`, `--yes`, `--app`, `--instance`                                                              |
| `clerk enable billing` / `clerk disable billing` | Toggle billing for users and/or orgs (defaults to both). For plans, pricing components, and entitlements, see the `clerk-billing` skill.                                                                                                                                                         | `--for <orgs\|users>`, `--dry-run`, `--yes`, `--no-skills` (enable only), `--app`, `--instance`                                                                                  |
| `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`                                                                                                                                                       |