Index of every page on this site: llms.txt
All skills
clerk avatar

/clerk-cli

@95f241a official
by clerkclerk/skills95 stars
6
Run it yourself

Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, impersonation, local webhook testing, deploy verification, instance config, security audits, Application Logs, env keys, feature toggles, and any Clerk Backend, Platform, or Frontend API call. Use when the user mentions Clerk management tasks, "list clerk users", "impersonate a user", "test webhooks locally", "enable orgs", "enable billing", "clerk security", "harden my Clerk instance", "clerk env pull", "clerk doctor", "clerk deploy", "clerk api", "clerk logs", "check the logs", "application logs", "why did this sign-in fail", "debug a sign-up", "what happened to this user", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

Use this Skill: https://skilld.dev/gh/clerk/skills/clerk-cli

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencescommands.md

≈3.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning1d3 checks · Risk SAFE
  • Gen Agent Trust Hub1d

    The skill provides a secure interface for managing Clerk resources through the official Clerk CLI. It incorporates extensive security practices, including mandatory health checks, dry-run previews for destructive actions, and clear warnings against exposing sensitive credentials in logs or chat. It uses standard package managers to fetch its binary, which is consistent with its intended use.

  • Socket1d

    No alerts

  • Snyk1d

    Risk: MEDIUM · 1 issue

Signed by skilld at 95f241a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago
  • CLI
  • TypeScript
  • clerk
  • authentication
  • user-management
  • backend-api
  • platform-api
  • env-management
  • instance-config
  • oauth

README badge

README badge for clerk/skills/clerk-cli

Operates the Clerk CLI for authentication, user/org/session management, deploy verification, instance config, and Backend/Platform API calls. Use when the user asks to list users, create organizations, pull environment keys, check deployment status, or run any ad-hoc Clerk API request—the CLI handles auth and key resolution automatically.

Generated from the current SKILL.md.

Does this skill work in a sandboxed environment?
Most Clerk CLI commands work best on the host shell. The CLI will warn when it detects sandboxed execution (no keychain access, blocked home directory, or network restrictions). Auth, linking, env pulls, and API calls may fail or report false negatives in a sandbox; rerun those commands on the host before trusting the results.
What do I need to do before running Clerk commands?
Run `clerk doctor --json` first to verify the CLI is installed, authenticated, linked to a project, and healthy. This catches setup failures (not logged in, project not linked, missing keys) upfront.
How do I invoke the Clerk CLI if the global binary is stale?
Fall back to a package runner: `bunx clerk@latest` (bun), `npx -y clerk@latest` (npm), `pnpm dlx clerk@latest` (pnpm), or `yarn dlx clerk@latest` (yarn 2+). The skill prefers the runner that matches the project's lockfile.
Can I use the Clerk CLI to call both Backend and Platform APIs?
Yes. `clerk api <path>` calls the Backend API by default. Add `--platform` to call the Platform API (account-level resources like applications and instances). Use `clerk api ls` and `clerk api ls --platform` to discover available endpoints.
How should I handle large responses from the CLI?
Save responses to a file first (e.g. `clerk users list --json > /tmp/users.json`), then query with `jq` or Python/Node to inspect only what you need. Do not print entire user lists or instance configs to the terminal.

Generated from the current SKILL.md. These answers refresh after source changes.