clerk-cli Skill: What It Does and How to Install It

Lets your coding agent run the Clerk CLI: manage users and orgs, call the Clerk API, pull keys, test webhooks and check deploys.

Installs: 34.8K; on skills.sh
Stars: 89; on GitHub
Files: 3; besides SKILL.md
Updated: Oct 2026; last repo commit

The SKILL.md tells the agent to use the clerk command line tool instead of hand-written HTTP calls. The tool handles sign-in, key lookup and app targeting. The agent first runs clerk doctor --json, finds endpoints with clerk api ls, and previews changes with --dry-run.

It loads for requests such as "list clerk users", "impersonate a user", "test webhooks locally", "enable orgs", "clerk env pull" and "clerk deploy". It needs the Clerk CLI and, for account-level work, a Clerk login or a Platform API key. The SKILL.md says to run it in your own shell rather than a sandbox, because sandboxes can block the keychain, browser and network access it uses.

Good for

Developers who manage Clerk users and orgs from the terminal
Teams debugging with user impersonation
Anyone testing Clerk webhooks on localhost
Teams checking a production deploy

Install clerk-cli

Claude Code

Copy this prompt.

Install the clerk-cli skill in Claude Code. Run this command:

/plugin marketplace add clerk/skills
/plugin install clerk@clerk-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route. The plugin installs all 20 skills in the Clerk repo (counted from the repo tree) and adds the Clerk MCP server from the repo's .mcp.json, which points at https://mcp.clerk.com/mcp. The skills-only routes install just this skill and no MCP server config. The skill drives the clerk command line tool, which is not installed by the skill. SKILL.md says the npm package is named clerk, to use a global clerk binary if one matches, and otherwise a package runner: bunx clerk@latest, npx -y clerk@latest, pnpm dlx clerk@latest or yarn dlx clerk@latest. It says not to teach npm install -g clerk as the main path, and clerk update refreshes the CLI. The README says to open /plugin, go to Marketplaces, select clerk-skills and enable auto-update if you want updates.

From the project README. Source.

What's in the skill

When it loads

Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, impersonation, local webhook testing, deploy verification, instance config, 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 env pull", "clerk doctor", "clerk deploy", "clerk api", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

Sections in SKILL.md

Execution environment (prefer the host, understand the sandbox warning)
Invoking the CLI
Prerequisites (run at session start for non-setup operations)
Accountless setup
The mental model
Discover endpoints - don't memorize them
The clerk api command (the workhorse)
Inspecting large outputs (do not flood your context)
Core commands at a glance
Agent-mode behavior (important)
Output format and errors
Safety rules for autonomous use
References

Key facts

Author: Clerk (the skill is in Clerk's own clerk/skills repo)
License: MIT (README, plugin.json and SKILL.md frontmatter; the repo has no LICENSE file)
Installs on skills.sh: 34,795 (Nov 2, 2026)
GitHub stars: 89 for the whole clerk/skills repo (Nov 2, 2026)
Last repo commit: Oct 30, 2026
What it includes: 4 files including SKILL.md and 3 reference files
Needs: The clerk CLI (global binary or a package runner), a browser sign-in with clerk auth login or CLERK_PLATFORM_API_KEY, and a linked Clerk app
Works in: Claude Code, Codex, Cursor and GitHub Copilot CLI through the plugin; any agent through npx skills

What it includes

Run clerk --version and clerk doctor --json before other commands.
The SKILL.md tells the agent to run doctor first. It reports login, link, keys and CLI version, and in agent mode warns when the run looks sandboxed.
Try: “Check that the Clerk CLI is logged in and linked”
Runs code · Doctor and session checks
clerk auth login, whoami, link, unlink, open.
Login opens a browser and stores a token. Link ties the repo to a Clerk app, and unlink needs --yes in agent mode.
Runs code · Auth and link
clerk init scaffolds Clerk; clerk env pull writes keys to your env file.
Init can start with temporary accountless keys. env pull merges keys into the framework env file. SKILL.md defers init to clerk-setup.
Try: “Pull my Clerk dev keys into .env.local”
Runs code · Init and env pull
Call Backend, Platform or Frontend API endpoints, with --dry-run for mutations.
Use clerk api ls to discover endpoints first. GET, POST, PATCH and DELETE all work, and --dry-run previews a change.
Try: “List the five newest Clerk users”
Delete · clerk api
clerk users list, create and open; organization and session recipes.
users create writes immediately with no confirmation in any mode. Recipes cover orgs, members, invitations, sessions and JWT templates. Source: references/recipes.md.
Try: “Ban the user with this email”
Delete · Users and orgs
clerk impersonate prints a sign-in URL for a user.
Needs clerk auth login and stamps every token with your email. Capture the printed token id to revoke it.
Write · Impersonate
clerk config pull, schema, patch and put.
patch is a partial update and put replaces everything. Both take --dry-run and --destructive.
Write · Instance config
clerk enable or disable orgs and billing.
Toggles Organizations or Billing on the instance, with --dry-run.
Write · Feature toggles
clerk webhooks listen, token and verify for local testing.
listen forwards deliveries to a local URL, token pins an inbox, verify checks a signature offline.
Try: “Forward Clerk webhooks to localhost:3000/api/webhooks”
Runs code · Webhooks
clerk deploy and clerk deploy status.
deploy is a production wizard; status checks DNS and OAuth readiness and exits 0 only when complete.
Runs code · Deploy

From the official docs

Permissions

High risk

The skill can create, change and delete live data in your Clerk instance, sign in as your users and write secret keys to your env file. Run it against a development instance first, preview every change with --dry-run and name the instance you mean.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can create, change and delete live Clerk data
The SKILL.md shows clerk api calls with -X DELETE and PATCH, clerk users create, clerk config patch and clerk config put against your instance. It says that in agent mode only unlink asks for --yes, every other confirmation is skipped, and --dry-run is the real safety net. Preview every mutation and pass --instance prod only when you mean it. github.com
It can sign in as one of your users
clerk impersonate creates a short-lived actor token and prints a sign-in URL. The SKILL.md says that on production it bypasses the user's MFA and may count against the impersonation quota, and to confirm with the user first. github.com
--fresh and deploy can orphan or create apps
The SKILL.md says clerk init --fresh replaces the temporary app and overwrites env keys with no prompt, orphaning the previous app and its users. clerk deploy --domain creates a production instance without prompting in agent mode. github.com
It writes secret keys to your env file
clerk env pull writes the publishable and secret keys into your env file, and --print writes them to stdout. The SKILL.md says never to read or show that output, and to keep the file out of git. github.com
Webhook testing goes through a relay
clerk webhooks listen opens a Svix relay inbox URL and forwards deliveries to your local handler. Only add that URL as a webhook endpoint if you want real events sent through it. github.com
It may run the CLI through npx
When no global binary matches, the SKILL.md runs the latest clerk package with a package runner, which downloads and runs code from npm. The plugin route also adds the Clerk MCP server. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only mode.
Talks to	Clerk Backend and Platform APIs through the clerk CLI. webhooks.clerk.com (webhook relay inbox URL, recipes.md)
Sign-in and keys	The SKILL.md says clerk auth login stores the OAuth token in the OS keychain, and CLERK_PLATFORM_API_KEY is the headless option.
Scopes	Your Clerk account (clerk auth login or CLERK_PLATFORM_API_KEY) Users, organizations and sessions in your Clerk instance Instance config and env files in your project

Questions

What does clerk-cli do?

It makes your coding agent run the Clerk CLI for Clerk work: users, organizations, sessions, API calls, env keys, instance config, impersonation, local webhook tests and deploy checks.

How do I install clerk-cli?

Use the install box above. The Claude Code plugin route installs every Clerk skill and the Clerk MCP server, and the skills CLI route installs only this skill. Pick one route, not both, or you get the skills twice.

Is clerk-cli official?

Yes. It is published in Clerk's own clerk/skills repository, and the plugin.json in that repo lists Clerk as the author.

Does clerk-cli work in the Claude app or Codex?

Codex, Cursor and GitHub Copilot CLI each have a plugin install in the README. The README does not document uploading Clerk skills to the Claude app, and this skill's job is to change code in a local project, so the install box has no Claude app tab.

Does it need a Clerk account or API key?

Account-level commands need a Clerk login or the CLERK_PLATFORM_API_KEY environment variable. The references say clerk init and some instance commands can work without an account, using temporary accountless keys.

Is clerk-cli safe to install?

It can create, change and delete data in your Clerk instance and sign in as users, so treat it as a tool with write access. Our advice: preview each change with --dry-run, name the instance with --instance, and run it against a development instance first. The SKILL.md says in agent mode only unlink requires --yes.

clerk-cli vs clerk-setup?

clerk-cli operates on an existing Clerk app: users, config, keys and deploy checks. The SKILL.md says that for setup or init requests, the clerk-setup skill is the source of truth and its guidance takes precedence.

Why does it say I am not logged in?

The SKILL.md says a sandboxed run can hide your keychain and Clerk config, so it reports not logged in even when you are. Rerun the same command in your own shell before you trust the result.

Information

updated Nov 2, 2026

Repository: clerk/skills
Folder: skills/clerk-cli

clerk/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 7

clerk-cli SKILL.md · github.com
clerk-cli auth.md · github.com
clerk-cli recipes.md · github.com
clerk-cli agent-mode.md · github.com
clerk/skills README · github.com
clerk plugin.json · github.com
clerk .mcp.json · github.com