Clerk Cli Skill 安全审计

7576Otherwise 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):7778| Project package manager   | Invocation                       |79| ------------------------- | -------------------------------- |80| bun (`bun.lock*`)         | `bunx clerk@latest`     |81| npm (`package-lock.json`) | `npx -y clerk@latest`   |82| pnpm (`pnpm-lock.yaml`)   | `pnpm dlx clerk@latest` |83| yarn >= 2 (`yarn.lock`)   | `yarn dlx clerk@latest` |8485Yarn 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.86

125126OAuth 2.0 PKCE flow against the Clerk OAuth system instance (`https://clerk.clerk.com` by default, overridable via `CLERK_OAUTH_BASE_URL`):1271281. Generates PKCE parameters.1292. Starts a local callback server on `127.0.0.1`.1303. Opens the browser to `/oauth/authorize`.1314. Exchanges the code at `/oauth/token` for an access token.1325. Fetches user info from `/oauth/userinfo`.1336. Stores the token in the OS credential store.134

158| `CLERK_MODE`             | Force `human` or `agent` mode (overrides TTY detection).        |159| `CLERK_SECRET_KEY`       | BAPI secret key (bypasses linked project / `--app` resolution). |160| `CLERK_PLATFORM_API_KEY` | PLAPI bearer key.                                               |161| `CLERK_BACKEND_API_URL`  | Override Backend API base URL.                                  |162| `CLERK_PLATFORM_API_URL` | Override Platform API base URL.                                 |163| `CLERK_OAUTH_BASE_URL`   | Override OAuth base URL (advanced / internal).                  |164| `CLERK_CONFIG_DIR`       | Override config, cache, and credential directory (advanced).    |165

220| `clerk link` / `clerk unlink` | Link this repo to a Clerk app, or remove the link. `unlink` requires `--yes` in agent mode.                                                                                                                                                                                                                         | (see `--help`)                                                                                                                                                                   |221| `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`)                                                                                                                                                                   |222| `clerk config {pull,schema}`  | Fetch instance config JSON, or its JSON Schema.                                                                                                                                                                                                                                                                     | (see `--help`)                                                                                                                                                                   |

240241```sh242# Pull dev keys into .env.local (auto-detects framework and key names)243clerk env pull244245# Pull production keys246clerk env pull --instance prod247248# Target a specific file249clerk env pull --file .env250```251252`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.253

2803. **Target explicitly in production:** pass `--instance prod` rather than relying on defaults, and confirm with the user before any production mutation.2814. **Never commit secrets:** `env pull` writes to `.env.local` (which should be gitignored). Don't paste secret keys into code or chat.2825. **Use `doctor --json`** to diagnose before assuming the CLI is broken.

247248# Target a specific file249clerk env pull --file .env250```251252`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.253

200201# 2. Add that relay URL as a webhook endpoint in the Clerk Dashboard.202#    Real events now stream to your terminal and forward to your local handler.203#    svix-* headers are preserved, so verifyWebhook() in your handler still204#    verifies against that endpoint's signing secret.205

205206# 3. Capture events for replay/verification (agent mode emits NDJSON automatically)207clerk webhooks listen --forward-to http://localhost:3000/api/webhooks --json > events.ndjson208209# 4. Verify a saved delivery offline against the endpoint's signing secret210clerk webhooks verify --secret whsec_... --delivery @event.json211```

4950**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.51

256- **`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.257- **`--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`.258- **`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.259- **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.260- **`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.

2792. **Preview mutations:** `--dry-run` on every `config patch`, `config put`, `api -X POST/PATCH/PUT/DELETE`.2803. **Target explicitly in production:** pass `--instance prod` rather than relying on defaults, and confirm with the user before any production mutation.2814. **Never commit secrets:** `env pull` writes to `.env.local` (which should be gitignored). Don't paste secret keys into code or chat.

165166To 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:167168```sh169clerk api /sign_in_tokens -d '{"user_id":"user_abc123"}'170```171

64| `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                                                                                                                                                                                                                                                                 |65| `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                                                           |66| `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                                                                                                                                                                                        |

176177**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.178