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). --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: 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 logs [list] |
Read the instance's Application Logs, newest first. list is the default subcommand, so bare clerk logs takes every list flag. JSON in agent mode: { data, cursor }; page with --cursor <cursor.next>. Logs go back as far as the plan's log retention. Time range: --since <duration> (30m, 2h, 7d, 1h30m) or --from <timestamp>, either with --to <timestamp> (ISO 8601, YYYY-MM-DD, or Unix ms; UTC without an offset). --since and --from can't be combined. Filters must all match unless --match any. --type takes an event type or a prefix with a trailing * (quote it: 'sign_in.*'). --user takes a user_... ID (actor or subject); --identifier takes an exact email, phone, username, or web3 wallet; neither combines with --actor/--subject, nor with each other. --payload-filter <path=value> (repeatable) and --fields <a,b> need --type; their paths come from clerk logs schema. --grouped shows one log_group per sign-in or sign-up flow with its events (--limit max 100); --group-type and --status need it. --follow prints the backfill, then polls for new logs, oldest first, as NDJSON with --json; it can't combine with --to, --cursor, or --grouped. Full detail in recipes.md. |
--since, --from, --to, --type, --user, --identifier, --actor, --subject, --session, --client, --ip, --trace, --impersonator, --payload-filter, --fields, --match <all|any>, --end-user-only, --grouped, --group-type <sign_in|sign_up>, --status <completed|failed>, --follow, --interval, --limit (1-500, default 50), --cursor, --json, --app, --instance, --secret-key |
clerk logs get <id> |
Every log of one flow, oldest first: a sign-in (sia_...) or sign-up (sua_...) ID, the group_id of a --grouped item. A log ID is a usage error. --cursor takes the previous page's cursor.next or a group's events_cursor. A group Clerk can't find in the targeted instance (wrong instance, past retention, or a few seconds old) fails with log_group_not_found. No time range, --follow, or group flags. |
--cursor, --limit (1-500, default 50), the list event filters (--type, --user, --payload-filter, ...), --json, --app, --instance, --secret-key |
clerk logs schema [event-type] |
Without an argument, every event type the instance can read, with its payload fields (--json returns them all in one call). With one, the payload fields of a type (sign_in.completed), a wildcard ('sign_in.*'), or a family (sign_in); for a wildcard or family, only the fields every matched type shares. Event types enabled per instance, such as sms.* and email.*, appear only once enabled. |
--json, --app, --instance, --secret-key |
clerk migrate … |
Export users from Auth0, Supabase, Firebase, Auth.js, Better Auth, WorkOS, or another Clerk instance (migrate export). Import them (migrate import), undo an import (migrate undo), and inspect runs and sources. migrate import and migrate undo write only with --yes. migrate export clerk exits 2 in agent mode until the source instance is named. Load the clerk-migrate skill. |
(see the clerk-migrate skill) |
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 |