Setting the file. One moment.
Subchapter 6.3
references/commands.mdMarkdown19 KBView on GitHub
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). --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 (opens in a new tab): 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). | --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. | --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 |