Skip to content
skillsafebeta
← Report library
Purpose / Other

Clerk Cli Skill Security Audit

What the author says it does (original text)

>-

Independent security check

Do not install or run it yet

Files checked
4
Risks found
8
Could it run dangerous commands?Looks for programs run straight after downloading, remote control of your computer, and hidden commands.Risks found: 1
Medium risk

The fallback installation path executes an unpinned clerk@latest package

Source references: 2
What we found

When a global CLI is unavailable or considered unsuitable, the Skill recommends fetching and executing latest through bunx, npx, pnpm dlx, or yarn dlx. The latest release can change, so the reviewed Skill text cannot establish what code will be downloaded later.

Why this matters

If the package supply chain, publisher account, or latest release is compromised, downloaded code runs with the agent's host permissions and may access Clerk credentials, project files, and the network.

When the global binary is unavailable or unsuitable, the Skill directs package runners to fetch and execute `clerk@latest`. That version is not pinned and can change with future releases, so this documentation audit cannot cover the package eventually run. Network installation is not inherently malicious, but users can require a reviewed fixed version, verify provenance, or use only a managed global installation.

SKILL.md:20In the instructionsOpen original file
> This skill targets clerk `latest`. If `clerk --version` disagrees with the latest available CLI, refresh it with `clerk update`, or invoke the latest through a package runner such as `bunx clerk@latest`. The binary is always the source of truth, so run `clerk <command> --help` to verify anything this skill claims.
Show 1 other places
SKILL.md:76In the instructionsOpen original file
Otherwise fall back to a package runner, in this order (matches the CLI's own `preferredRunner` logic, which prefers the runner that matches the project's lockfile):| Project package manager   | Invocation                       || ------------------------- | -------------------------------- || bun (`bun.lock*`)         | `bunx clerk@latest`     || npm (`package-lock.json`) | `npx -y clerk@latest`   || pnpm (`pnpm-lock.yaml`)   | `pnpm dlx clerk@latest` || yarn >= 2 (`yarn.lock`)   | `yarn dlx clerk@latest` |Yarn Classic (v1) has no `dlx`; treat those projects as "no preferred runner" and fall back to the first runner from the list above that's on PATH.
Could it expose your files or keys?Looks for uploads of files containing passwords or keys, and keys written directly in the code.Risks found: 3
High risk

Environment variables can redirect credential-bearing API or OAuth traffic to another server

Source references: 3
What we found

The CLI accepts Backend, Platform, and OAuth base-URL overrides while authenticating requests with an instance secret key, platform API key, or OAuth token. If a repository environment, CI job, or shell predefines a malicious override, credentials may be sent to a non-Clerk endpoint.

Why this matters

An attacker could obtain Clerk keys or OAuth tokens and use them to read or alter users, organizations, sessions, configuration, and billing information.

The documentation says Backend, Platform, and OAuth requests use a secret key, platform key, or OAuth token, while environment variables can override all three base URLs. If project scripts, CI, or the shell predefines an untrusted URL, later authenticated requests could send credentials there. The source does not show a malicious value or an actual leak; users can inspect and clear these URL overrides before use.

references/auth.md:9In the instructionsOpen original file
| API                      | Base URL                    | Auth                                                                   | Used for                                                                                           | CLI flag     || ------------------------ | --------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------ || **Backend API (BAPI)**   | `https://api.clerk.dev/v1/` | Instance **secret key** (`sk_...`)                                     | Tenant data: users, orgs, sessions, invitations, JWT templates, webhooks.                          | (default)    || **Platform API (PLAPI)** | `https://api.clerk.com/v1/` | **Platform API key** (`ak_...`) or OAuth token from `clerk auth login` | Account-level: listing your applications, fetching app/instance metadata, pulling config, billing. | `--platform` |You override the base URLs via `CLERK_BACKEND_API_URL` and `CLERK_PLATFORM_API_URL` when testing against non-production Clerk environments.
Show 2 other places
references/auth.md:126In the instructionsOpen original file
OAuth 2.0 PKCE flow against the Clerk OAuth system instance (`https://clerk.clerk.com` by default, overridable via `CLERK_OAUTH_BASE_URL`):1. Generates PKCE parameters.2. Starts a local callback server on `127.0.0.1`.3. Opens the browser to `/oauth/authorize`.4. Exchanges the code at `/oauth/token` for an access token.5. Fetches user info from `/oauth/userinfo`.6. Stores the token in the OS credential store.
references/auth.md:159In the instructionsOpen original file
| `CLERK_MODE`             | Force `human` or `agent` mode (overrides TTY detection).        || `CLERK_SECRET_KEY`       | BAPI secret key (bypasses linked project / `--app` resolution). || `CLERK_PLATFORM_API_KEY` | PLAPI bearer key.                                               || `CLERK_BACKEND_API_URL`  | Override Backend API base URL.                                  || `CLERK_PLATFORM_API_URL` | Override Platform API base URL.                                 || `CLERK_OAUTH_BASE_URL`   | Override OAuth base URL (advanced / internal).                  || `CLERK_CONFIG_DIR`       | Override config, cache, and credential directory (advanced).    |
Medium risk

env pull writes Clerk secret keys into project environment files

Source references: 5
What we found

The command materializes publishable and secret keys and permits --file to target files such as .env. Although the instructions warn against committing secrets, safety still depends on the chosen file being ignored and appropriately protected.

Why this matters

Keys may enter version control, backups, build artifacts, logs, or become readable by other local processes, exposing Clerk tenant privileges. Production keys have greater impact.

The intended behavior of `clerk env pull` is to write publishable and secret keys into a project environment file, with `--file` selecting the destination. The documentation says `.env.local` should be gitignored but does not guarantee file permissions or ignore rules. Keys could be exposed if the target is committed, backed up, or readable by others; users can verify the path, permissions, and version-control status first.

SKILL.md:37In the instructionsOpen original file
  misreport "not linked".- **Local `.env*` files**: publishable and secret keys materialized by  `clerk env pull`.- **Outbound network access to Clerk**: every Backend and Platform API call.
Show 4 other places
SKILL.md:221In the instructionsOpen original file
| `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`.                                                                                                                              | (see `--help`)                                                                                                                                                                   || `clerk config {pull,schema}`  | Fetch instance config JSON, or its JSON Schema.                                                                                                                                                                                                                                                                     | (see `--help`)                                                                                                                                                                   |
references/recipes.md:241In the instructionsOpen original file
```sh# Pull dev keys into .env.local (auto-detects framework and key names)clerk env pull# Pull production keysclerk env pull --instance prod# Target a specific fileclerk env pull --file .env````env pull` merges into the existing file: existing Clerk keys are updated in place; new ones are appended under a `# Clerk` header; everything else is preserved.
SKILL.md:281In the instructionsOpen original file
3. **Target explicitly in production:** pass `--instance prod` rather than relying on defaults, and confirm with the user before any production mutation.4. **Never commit secrets:** `env pull` writes to `.env.local` (which should be gitignored). Don't paste secret keys into code or chat.5. **Use `doctor --json`** to diagnose before assuming the CLI is broken.
references/recipes.md:248In the instructionsOpen original file
# Target a specific fileclerk env pull --file .env````env pull` merges into the existing file: existing Clerk keys are updated in place; new ones are appended under a `# Clerk` header; everything else is preserved.
Medium risk

The local webhook recipe can persist real event data to a file

Source references: 3
What we found

The recipe sends real Clerk events through the relay to the terminal and demonstrates redirecting them into events.ndjson. Webhook payloads may contain user, organization, or session fields, and the file is not automatically removed.

Why this matters

Event data may remain in the project directory, enter version control or backups, or become readable by other local users.

The recipe says real webhook events stream to the terminal and demonstrates redirecting agent-mode NDJSON into `events.ndjson` in the workspace. This persistently records event contents; sensitivity depends on the actual webhook payload, and the source does not describe automatic cleanup or file permissions. Users can require test events only, a restricted temporary location, and an agreed deletion time.

references/recipes.md:194In the instructionsOpen original file
`listen` talks only to the Svix relay and `verify` is pure local HMAC - neither needs auth or a linked project.```sh# 1. Mint a token and open a pinned tunnel that forwards deliveries to your handler.#    The command prints a relay inbox URL (https://webhooks.clerk.com/in/c_.../).clerk webhooks listen --token "$(clerk webhooks token)" --forward-to http://localhost:3000/api/webhooks# 2. Add that relay URL as a webhook endpoint in the Clerk Dashboard.#    Real events now stream to your terminal and forward to your local handler.#    svix-* headers are preserved, so verifyWebhook() in your handler still#    verifies against that endpoint's signing secret.# 3. Capture events for replay/verification (agent mode emits NDJSON automatically)clerk webhooks listen --forward-to http://localhost:3000/api/webhooks --json > events.ndjson
Show 2 other places
references/recipes.md:201In the instructionsOpen original file
# 2. Add that relay URL as a webhook endpoint in the Clerk Dashboard.#    Real events now stream to your terminal and forward to your local handler.#    svix-* headers are preserved, so verifyWebhook() in your handler still#    verifies against that endpoint's signing secret.
references/recipes.md:206In the instructionsOpen original file
# 3. Capture events for replay/verification (agent mode emits NDJSON automatically)clerk webhooks listen --forward-to http://localhost:3000/api/webhooks --json > events.ndjson# 4. Verify a saved delivery offline against the endpoint's signing secretclerk webhooks verify --secret whsec_... --delivery @event.json```
Could it delete files or keep running?Looks for broad file deletion, disk overwrites, and programs set to start automatically.Risks found: 1
Medium risk

clerk init --fresh overwrites key files without prompting and orphans the prior app and users

Source references: 1
What we found

The Skill states that --fresh replaces the temporary application and overwrites environment keys and .clerk/keyless.json without confirmation. The previous application and its users become orphaned from the project.

Why this matters

The project may immediately point to a new application, existing users may no longer be reachable through the current configuration, and prior key or app-link information may be difficult to recover.

The documentation explicitly marks `--fresh` as destructive: it replaces the temporary app without prompting and overwrites environment keys and `.clerk/keyless.json`, orphaning the prior app and its users from the current project. This occurs only when `clerk init --fresh` is used; an ordinary init is not the same operation. Users can prohibit this flag unless replacement is explicitly approved.

SKILL.md:257In the instructionsOpen original file
- **`init` needs no login — do not log in first.** An unauthenticated agent run mints an unclaimed accountless app with temporary dev keys: no flag, no account, no browser. `--app <id>` or a pre-link targets a real app instead; `--accountless` forces the temporary-keys path over both a session and an existing link. `--keyless` remains a deprecated compatibility alias. A framework without temporary-key support and no app target prints manual guidance and exits cleanly. Flag exclusivity is in the command table above.- **`--fresh` is destructive.** It replaces the temporary app and overwrites the env keys and `.clerk/keyless.json` breadcrumb with no prompt, orphaning the previous app and its users. Never pass it just to re-run `init`.- **`unlink` requires `--yes` in agent mode.** It gates on `isAgent() && !options.yes` and exits with a usage error without it. This is the exception, not the pattern - see the next bullet.
Could it bypass safety checks?Looks for skipped website security checks, excessive file access, or actions that skip your approval.Risks found: 2
High risk

Agent mode bypasses most mutation confirmations and may auto-select a production key

Source references: 4
What we found

Agent mode silently skips confirmation for configuration, API, user-creation, and feature-toggle mutations. Without an explicit application, the CLI can also use any local sk_ key it finds, including sk_live_. A call missing a dry run or target can therefore change production immediately.

Why this matters

It could create or delete users, ban accounts, revoke sessions, alter organization or billing settings, or replace instance configuration.

Agent mode skips most confirmations except unlink, so a mutation without `--dry-run` can execute immediately. With no app or link, the CLI may use any locally found `sk_` key, including a production key. If `sk_live_` is present, an omitted target can therefore cause an unconfirmed production change. Users can require explicit `--app`/`--instance` and review a dry run first.

references/agent-mode.md:57In the instructionsOpen original file
| `unlink` confirmation                                            | Prompt y/n                                                       | Requires `--yes`; exits with a usage error without it || All other mutation confirmations (`config patch` / `put`, `api -X POST/PATCH/DELETE`, `users create`, `enable` / `disable`) | Prompt y/n | **Silently skipped - the mutation executes.** These gates are `isHuman() && !options.yes`, so agent mode bypasses them entirely: `--yes` is neither required nor meaningful, and nothing errors. `--dry-run` is the only safety net                                                                                                                                                                                                                                                                                                                                                                                                     || `clerk doctor --fix`                                             | Interactively offers fixes                                       | **Ignored**; output the `remedy` field and let the caller act                                                                                                                                                                                                                                                                                                                                                                        |
Show 3 other places
references/auth.md:50In the instructionsOpen original file
**It follows the key, not the app.** No `--app` and no link means the CLI uses whatever local `sk_` key it finds — `sk_live_` included, claimed or not. In an unlinked repo a production key in `.env.local` is what gets mutated, unconfirmed in agent mode. Pass `--app <id>` when you mean a real application.
SKILL.md:257In the instructionsOpen original file
- **`init` needs no login — do not log in first.** An unauthenticated agent run mints an unclaimed accountless app with temporary dev keys: no flag, no account, no browser. `--app <id>` or a pre-link targets a real app instead; `--accountless` forces the temporary-keys path over both a session and an existing link. `--keyless` remains a deprecated compatibility alias. A framework without temporary-key support and no app target prints manual guidance and exits cleanly. Flag exclusivity is in the command table above.- **`--fresh` is destructive.** It replaces the temporary app and overwrites the env keys and `.clerk/keyless.json` breadcrumb with no prompt, orphaning the previous app and its users. Never pass it just to re-run `init`.- **`unlink` requires `--yes` in agent mode.** It gates on `isAgent() && !options.yes` and exits with a usage error without it. This is the exception, not the pattern - see the next bullet.- **Only `unlink` actually requires `--yes`.** Every other confirmation gate is written as `isHuman() && !options.yes`, so agent mode skips it outright: the mutation executes with no prompt and no error. Passing `--yes` is harmless but changes nothing. Do not treat it as a safety gate - `--dry-run` is the real one.- **`impersonate` requires the `[user]` positional in agent mode.** If a search term matches multiple users, it exits `2` listing candidate user IDs — retry with a specific `user_...` ID. Output is a JSON object (`{url, id, userId, actor, ...}`); surface `url` to the user and capture `id` — it is the only chance to record the revoke handle.
SKILL.md:280In the instructionsOpen original file
2. **Preview mutations:** `--dry-run` on every `config patch`, `config put`, `api -X POST/PATCH/PUT/DELETE`.3. **Target explicitly in production:** pass `--instance prod` rather than relying on defaults, and confirm with the user before any production mutation.4. **Never commit secrets:** `env pull` writes to `.env.local` (which should be gitignored). Don't paste secret keys into code or chat.
High risk

Impersonation can bypass user MFA, while the raw API can create sign-in tokens without an actor audit trail

Source references: 3
What we found

The Skill can generate impersonation sign-in URLs, and the production flow bypasses the user's MFA. Its recipe also exposes /sign_in_tokens, which permits signing in as the target user without the actor audit trail provided by impersonation.

Why this matters

Anyone obtaining the generated URL or token may access the target account while it remains valid. With a raw sign-in token, investigators also lose the impersonation actor marker.

The Skill explicitly supports impersonation, which bypasses the target user's MFA in production, although it requires user confirmation and stamps actor tokens for auditing. A separate raw-API recipe creates a one-time sign-in token without that actor audit trail. Overbroad authorization or a leaked URL could expose the target account. Users can restrict this to development, name the exact user, and forbid sign-in tokens without explicit approval.

SKILL.md:230In the instructionsOpen original file
| `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`)                                                                                                                                                                   |
Show 2 other places
references/recipes.md:166In the instructionsOpen original file
To mint a one-time **sign-in token** instead - for building custom token sign-in flows, signing in *as* the user with no actor audit trail - use the raw API:```shclerk api /sign_in_tokens -d '{"user_id":"user_abc123"}'```
references/agent-mode.md:65In the instructionsOpen original file
| `clerk open [subpath]`                                           | Opens the browser to the URL                                     | Does not open a browser. Prints a JSON descriptor (`{url, appId, appName, instanceId, instanceLabel, subpath, opened: false}`) on stdout so the agent can surface it                                                                                                                                                                                                                                                                 || `clerk impersonate [user]`                                       | Picker when `[user]` omitted; confirms; prints URL + revoke hint | Requires the `[user]` positional (usage error `2` without it). Ambiguous search terms exit `2` listing candidate user IDs - retry with a `user_...` ID. Never opens a browser. Prints one JSON object `{url, id, userId, actor, appId, appLabel, instanceId, instanceLabel, expiresInSeconds}` on stdout - capture `id`; it is the only chance to record the revoke handle                                                           || `clerk webhooks listen --forward-to <url>`                       | Banner + one formatted line per delivery                         | NDJSON on stdout: one `{type:"ready", relay_url, forward_to}` line, then one `event` line per delivery (feed lines to `webhooks verify --delivery`), plus `{type:"reconnecting"}` if the relay drops. Long-running - run it in the background                                                                                                                                                                                        |
Could it mislead the AI or hide text?Checks the skill instructions for requests to ignore you, influence the report, or hide text in invisible characters.Risks found: 1
High risk

Requires a helper to run automatically and out of sight

Source references: 2
What we found

The skill combines automatic execution with instructions not to ask or tell the user.

Why this matters

If the AI follows this text, it may stop following your instructions or skip actions that normally need your approval.

Legitimate use of this code

This is not an instruction to conceal or secretly add operations. It warns that agent mode skips most interactive confirmations, mutations execute directly, and `--dry-run` is the only safety measure. The text exposes the risk rather than directing covert execution.

This assessment concerns the code and conditions shown, not proof that harm has occurred.
references/agent-mode.md:57In the instructionsOpen original file
| `unlink` confirmation                                            | Prompt y/n                                                       | Requires `--yes`; exits with a usage error without it || All other mutation confirmations (`config patch` / `put`, `api -X POST/PATCH/DELETE`, `users create`, `enable` / `disable`) | Prompt y/n | **Silently skipped - the mutation executes.** These gates are `isHuman() && !options.yes`, so agent mode bypasses them entirely: `--yes` is neither required nor meaningful, and nothing errors. `--dry-run` is the only safety net                                                                                                                                                                                                                                                                                                                                                                                                     || `clerk doctor --fix`                                             | Interactively offers fixes                                       | **Ignored**; output the `remedy` field and let the caller act                                                                                                                                                                                                                                                                                                                                                                        |
Show 1 other places
SKILL.md:177In the instructionsOpen original file
**Always `--dry-run` a mutation before running it for real.** Then re-run without `--dry-run` (add `--yes` if you're sure). In agent mode, interactive confirmation is bypassed, so `--dry-run` is the only safety net for destructive calls.
Could it change links or payment recipients without asking?Looks for forced referral or payment changes combined with instructions to hide the change.No risks found

Inside this skill

8 instruction sections

This Skill instructs an agent to operate the Clerk CLI across authentication, users, organizations, sessions, configuration, billing, deployment, impersonation, and arbitrary Backend/Platform API requests. It relies on locally stored OAuth or platform credentials and can access Clerk tenant data.

View source
SKILL.md:4In the instructionsOpen original file
description: >-  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.license: MIT
references/auth.md:9In the instructionsOpen original file
| API                      | Base URL                    | Auth                                                                   | Used for                                                                                           | CLI flag     || ------------------------ | --------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------ || **Backend API (BAPI)**   | `https://api.clerk.dev/v1/` | Instance **secret key** (`sk_...`)                                     | Tenant data: users, orgs, sessions, invitations, JWT templates, webhooks.                          | (default)    || **Platform API (PLAPI)** | `https://api.clerk.com/v1/` | **Platform API key** (`ak_...`) or OAuth token from `clerk auth login` | Account-level: listing your applications, fetching app/instance metadata, pulling config, billing. | `--platform` |

The Skill explicitly recommends dry-running changes, naming production targets, and obtaining user confirmation before production mutations. These are instruction-level safeguards; the CLI itself does not prompt for most mutations in agent mode.

View source
SKILL.md:276In the instructionsOpen original file
## Safety rules for autonomous use1. **Discover before acting:** `clerk api ls <keyword>` before `clerk api <path>`.2. **Preview mutations:** `--dry-run` on every `config patch`, `config put`, `api -X POST/PATCH/PUT/DELETE`.3. **Target explicitly in production:** pass `--instance prod` rather than relying on defaults, and confirm with the user before any production mutation.4. **Never commit secrets:** `env pull` writes to `.env.local` (which should be gitignored). Don't paste secret keys into code or chat.5. **Use `doctor --json`** to diagnose before assuming the CLI is broken.
references/agent-mode.md:56In the instructionsOpen original file
| `clerk link` without `--app`                                     | Interactive picker / create UI                                   | Tries silent autolink from detected publishable keys; if no deterministic match exists, exits with a usage error telling the caller to pass `--app`                                                                                                                                                                                                                                                                                  || `unlink` confirmation                                            | Prompt y/n                                                       | Requires `--yes`; exits with a usage error without it || All other mutation confirmations (`config patch` / `put`, `api -X POST/PATCH/DELETE`, `users create`, `enable` / `disable`) | Prompt y/n | **Silently skipped - the mutation executes.** These gates are `isHuman() && !options.yes`, so agent mode bypasses them entirely: `--yes` is neither required nor meaningful, and nothing errors. `--dry-run` is the only safety net                                                                                                                                                                                                                                                                                                                                                                                                     || `clerk doctor --fix`                                             | Interactively offers fixes                                       | **Ignored**; output the `remedy` field and let the caller act                                                                                                                                                                                                                                                                                                                                                                        || `clerk apps list` default output                                 | Table                                                            | JSON (when piped)                                                                                                                                                                                                                                                                                                                                                                                                                    |

Authentication and target selection depend on the host keychain, home-directory configuration, repository links, and local environment files. A sandbox can produce misleading failures when this state is unavailable, so the instructions require host-side verification.

View source
SKILL.md:29In the instructionsOpen original file
- **OS credential store**: `clerk auth login` stores the OAuth token in the  system keychain. A sandbox without keychain access reports "not logged in"  even when the host is authenticated.- **Home-directory Clerk state**: saved config, cached metadata, and fallback  credentials live under the user's Clerk config/data directories.- **Linked project metadata**: resolved from the repo's git remote plus Clerk  config. Sandboxes with stripped repo state or blocked home-dir reads can  misreport "not linked".- **Local `.env*` files**: publishable and secret keys materialized by  `clerk env pull`.- **Outbound network access to Clerk**: every Backend and Platform API call.- **Browser + localhost OAuth callback**: `clerk auth login` needs both.
Start here · InstructionsSKILL.md
clerk-cli
Lines connect the instruction file to its sections, not an observed execution order. Select a section to read the source. 5 more sections are available in the original file.

File reference map

References: 4
Files making referencesReferenced content
Lines show actual file references, not execution order. Select a node to highlight its connections and inspect the files and source locations. Dashed lines include files that still need locating.
Files and check records4 files

Coverage and gaps

Content covered in each file

These are the source ranges included in this check, not a guarantee that every issue has been resolved.

  • SKILL.mdFull text included
  • references/agent-mode.mdFull text included
  • references/auth.mdFull text included
  • references/recipes.mdFull text included

This report is for the version above. We read the available code and instructions without running the skill or checking extra packages it installs. This is not a promise of safety: a different version or setup may behave differently.

  • SKILL.mdInstructions
  • references/agent-mode.mdSupporting file
  • references/auth.mdSupporting file
  • references/recipes.mdSupporting file

Operations mentioned in code and instructions

Connect to websites
SKILL.md:18In the instructionsOpen original file
The `clerk` binary is a pre-authenticated gateway to Clerk's Backend API and Platform API, plus project-level tooling (auth, linking, env pulls, instance config). When the user asks anything that touches a Clerk resource, reach for `clerk` first instead of hand-rolling `curl`.
references/agent-mode.md:238In the instructionsOpen original file
  "oauth": { "complete": true, "configured": ["google"], "pending": [], "unsupported": [] },  "nextAction": "SSL still provisioning for example.com. Re-run `clerk deploy status` in a few minutes, DNS propagation can take time. Ask the user to visit the Clerk Dashboard domains page, or offer to open it: https://dashboard.clerk.com/apps/app_.../instances/ins_.../domains"}
references/auth.md:11In the instructionsOpen original file
| ------------------------ | --------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------- …| **Backend API (BAPI)**   | `https://api.clerk.dev/v1/` | Instance **secret key** (`sk_...`)                                     | Tenant data: users, orgs, sessions, invitations, JWT templates, webhooks.                          | (default)    || **Platform API (PLAPI)** | `https://api.clerk.com/v1/` | **Platform API key** (`ak_...`) or OAuth token from `clerk auth login` | Account-level: listing your applications, fetching app/instance metadata, pulling config, billing. | `--plat …
Read keys or account settings
SKILL.md:25In the instructionsOpen original file
Most AI coding agents default to running shell commands in a sandbox where theuser's home directory, OS keychain, browser launch, localhost callbackbinding, or network access may be blocked. The Clerk CLI depends on all of
SKILL.md:30In the instructionsOpen original file
- **OS credential store**: `clerk auth login` stores the OAuth token in the  system keychain. A sandbox without keychain access reports "not logged in"  even when the host is authenticated.
SKILL.md:33In the instructionsOpen original file
- **Home-directory Clerk state**: saved config, cached metadata, and fallback  credentials live under the user's Clerk config/data directories.- **Linked project metadata**: resolved from the repo's git remote plus Clerk
Install extra software packages
SKILL.md:81In the instructionsOpen original file
| bun (`bun.lock*`)         | `bunx clerk@latest`     || npm (`package-lock.json`) | `npx -y clerk@latest`   || pnpm (`pnpm-lock.yaml`)   | `pnpm dlx clerk@latest` |
SKILL.md:87In the instructionsOpen original file
The published npm package is **`clerk`**, not `@clerk/cli`. Never teach `npm install -g clerk` as the primary path. If the global CLI is stale or behaves differently from this skill, either upgrade the global install or fall back to the `latest` runner form above.
Read files
SKILL.md:153In the instructionsOpen original file
clerk api /users --file payload.jsoncat payload.json | clerk api /users
SKILL.md:206In the instructionsOpen original file
```shpython3 -c 'import json; d=json.load(open("/tmp/users.json")); print(len(d["data"]), d["hasMore"])'node -e 'const d=require("/tmp/users.json"); console.log(d.data.length, d.hasMore)'
SKILL.md:266In the instructionsOpen original file
- **`deploy` has an agent handoff plus a verification gate.** In agent mode, bare `clerk deploy` is read-only and emits a JSON handoff. It never drives the interactive wizard. Do not tell Claude or another agent to run `! clerk deploy`, bec …- **`--input-json <json|@file|->`** expands JSON into flags on any command (e.g. `clerk init --input-json '{"framework":"next","yes":true}'`). Stdin needs the explicit `-` marker (`echo '{"yes":true}' | clerk init --input-json -`); bare piped stdin is **not** auto-detected, so shell loops and self-reading commands (`cat body.json | clerk api …`) are untouched. Place `--input-json` after the leaf subcommand. Full rules in [references/agent-mode.md](references/agent-mode.md#passing-options-as-json---input-json).
Run commands
SKILL.md:243In the instructionsOpen original file
| `clerk api ls [filter]`       | Discover endpoints from the bundled OpenAPI catalog.                                                                                                                                                           …| `clerk completion [shell]`    | Print a shell completion script (`bash`, `zsh`, `fish`, `powershell`).                                                                                                                                                                                                                                              | -                                                                                                                                                                                || `clerk update`                | Update the CLI to the latest version.                                                                                                                                                                          …
Lines read
1,106
File checksum (to compare versions)
228ce464bb4d16cde83901dd6790a94bdee987985848f082d5990c0c6b02fe9d