# Add Clerk authentication to a Next.js app with the Clerk CLI

**How do I add Clerk authentication to a Next.js app with the Clerk CLI?**

Run `clerk init` against a [Next.js](https://clerk.com/glossary/next-js.md) 16 [App Router](https://clerk.com/glossary/app-router.md) project — the [Clerk CLI](https://clerk.com/changelog/2026-04-22-clerk-cli.md) (released 2026-04-22) installs `@clerk/nextjs` v7, writes `proxy.ts` (the Next.js 16 [middleware](https://clerk.com/glossary/middleware.md) replacement, [per the release notes](https://nextjs.org/blog/next-16)), wires [`ClerkProvider`](https://clerk.com/glossary/clerkprovider.md) into the layout, and scaffolds sign-in and sign-up routes. Then run `clerk env pull` to write your [publishable key](https://clerk.com/glossary/publishable-key.md) and [secret key](https://clerk.com/glossary/secret-key.md) into `.env.local`, `clerk doctor` to validate the wiring, and `clerk config patch` to manage [passkeys](https://clerk.com/glossary/passkeys.md), sign-in methods, and password policy as code you can commit. The walkthrough below goes end-to-end against a fresh starter and shows how to inspect users with `clerk api`.

Before 2026-04-22, adding Clerk to Next.js meant three things in three places — install the [SDK](https://clerk.com/glossary/software-development-kit-sdk.md) in your terminal, copy keys out of the dashboard, and hand-edit `layout.tsx` and `middleware.ts` in your editor. The CLI replaces that _default_ path; the dashboard remains the escape hatch (`clerk open`) for OAuth provider client secrets, billing, and other operations that still live there.

## 1. Why the Clerk CLI

Before 2026-04-22, adding Clerk to a Next.js app meant three things in three places: install the [SDK](https://clerk.com/glossary/software-development-kit-sdk.md) in your terminal, copy keys out of the Clerk Dashboard, and hand-edit `layout.tsx` and `middleware.ts` in your editor. Every "Add Clerk to Next.js" tutorial led with `pnpm add @clerk/nextjs`, a dashboard tab, and a block of boilerplate to paste in. The CLI replaces that round-trip.

`clerk init` installs the SDK, writes `proxy.ts` (the Next.js 16 [middleware](https://clerk.com/glossary/middleware.md) replacement, [per the Next.js 16 release notes](https://nextjs.org/blog/next-16)), wires [`ClerkProvider`](https://clerk.com/glossary/clerkprovider.md) into the layout, and scaffolds sign-in and sign-up routes. `clerk env pull` writes your [publishable key](https://clerk.com/glossary/publishable-key.md) and [secret key](https://clerk.com/glossary/secret-key.md) straight to `.env.local`. `clerk config pull` and `clerk config patch` let you treat Clerk's instance configuration like any other file in your repo: code-reviewable, versionable, diff-able, scriptable from CI. `clerk doctor` is a first-class preflight that catches missing envs, broken providers, or stale SDK versions before the dev server does. `clerk api` is an authenticated terminal for the Backend API so you can explore users, sessions, and organizations without hand-rolling `curl` commands.

The CLI does not replace the dashboard — some operations (OAuth provider client secrets, billing) still live there, and `clerk open` is the escape hatch. It replaces the _default_ path: the one you hit at the start of every new project.

## 2. Prerequisites

Before starting, confirm you have:

- [ ] Node.js 20.9 or newer (the [minimum for Next.js 16](https://nextjs.org/blog/next-16#version-requirements); Node.js 18 is no longer supported)
- [ ] A [node package manager](https://clerk.com/glossary/node-package-manager.md) — pnpm, npm, yarn, or bun (this guide uses pnpm; the CLI's `--pm` flag accepts any)
- [ ] A Clerk account — the free Hobby tier is enough for `init`, `env pull`, `doctor`, `api`, and the access-control patch in this guide; the passkey and custom-password-policy patches require a paid plan (see [pricing](https://clerk.com/pricing))
- [ ] An editor, terminal, and a browser signed into your Clerk account so `clerk auth login` can complete

Intermediate [TypeScript](https://clerk.com/glossary/typescript.md) comfort helps but is not required — the starter is a standard Next.js 16 App Router project, and the configuration patches are plain JSON.

## 3. Install or update the Clerk CLI

Install globally with your preferred package manager:

**pnpm**

filename: terminal
```sh
pnpm add -g clerk
```

**npm**

filename: terminal
```sh
npm install -g clerk
```

**Homebrew**

filename: terminal
```sh
brew install clerk/stable/clerk
```

**curl**

filename: terminal
```sh
curl -fsSL https://clerk.com/install | bash
```

Running it once without installing is also supported via `npx clerk` or `bunx clerk`, which is the right call for CI or one-shot scripts where a global install is overkill.

If you already have it, update to the latest release:

```bash
clerk update
```

Use `clerk update --channel canary` to ride the unstable channel, and `clerk update --all` to update _every_ `clerk` binary found on your PATH — useful if you have the CLI installed via multiple package managers (say, pnpm plus Homebrew) and want them all on the same version. Agent skills update separately, via `clerk skill install` (see next section). Verify the install:

```bash
clerk --version
```

> Enable shell completion once and forget it exists. For zsh: `clerk completion zsh >> ~/.zshrc` and open a new terminal. Bash and fish are supported via the same subcommand.

## 4. Install the Clerk agent skill and update existing Clerk skills

Clerk ships a bundled set of agent skills — the core `clerk` skill for the CLI itself plus framework-specific skills like `clerk-nextjs-patterns`, `clerk-react-patterns`, and `clerk-tanstack-patterns` — that teach AI coding harnesses (Claude Code, Cursor, Copilot) how to use Clerk correctly. Install them once globally:

```bash
clerk skill install
```

The CLI detects your scope (user-level `~/.claude/skills/` by default) and installs every Clerk-maintained skill into it. If you want project-local install instead, run the command inside a project directory with a `.claude/` folder present.

> Skills drift. If you installed Clerk skills months ago, re-run `clerk skill install` periodically — not just when you start a new article or project. The bundle refreshes alongside Clerk's SDKs, and an out-of-date skill is worse than no skill because it teaches stale APIs confidently. Make it a recurring habit.

The skills give your agent current, version-matched Clerk knowledge — for example, they know `@clerk/nextjs` v7 exports `<Show when="signed-in">` rather than the removed `<SignedIn>` / `<SignedOut>` components, so the code your agent generates matches the code the CLI scaffolds. This pattern — CLI-installed, version-pinned agent skills — is the same model [Next.js](https://nextjs.org/docs/app/guides/ai-agents) and [shadcn/ui](https://ui.shadcn.com/docs/skills) have adopted.

## 5. Log in and pick an application

Authenticate the CLI with your Clerk account. This opens a browser [OAuth](https://clerk.com/glossary/oauth.md) flow and returns a token the CLI stores locally:

```bash
clerk auth login
clerk whoami
```

`clerk whoami` prints the account email and the active instance, which is how you verify the login stuck.

List the Clerk applications your account can access:

```bash
clerk apps list
```

The output includes each app's ID (`app_…`), name, and instance types. You can create a new app from the terminal with `clerk apps create <name>`, which is useful when scripting onboarding or spinning up a throwaway instance for testing. If you need the dashboard for anything the CLI does not cover yet — custom OAuth credentials, billing, analytics — `clerk open` opens the currently-linked application in your browser.

## 6. Scaffold a Next.js app with `clerk init --starter`

From the directory where you want the new project to live:

```bash
clerk init --starter --framework next --pm pnpm --name my-clerk-next-app
```

`--starter` tells the CLI to scaffold a new project from a template rather than integrate into the current directory. `--framework next` selects the Next.js starter; `--pm pnpm` chooses your package manager; `--name` names the directory. Omit `--name` and the CLI prompts you interactively.

The starter generates a Next.js 16 App Router project pinned to `next@16.2.4`, `react@19.2.4`, and `@clerk/nextjs@^7.2.5`, with the following layout:

```
my-clerk-next-app/
├─ app/
│  ├─ layout.tsx        # ClerkProvider, <Show when="..."> header, UserButton
│  ├─ page.tsx
│  ├─ sign-in/[[...sign-in]]/page.tsx
│  └─ sign-up/[[...sign-up]]/page.tsx
├─ proxy.ts             # clerkMiddleware + createRouteMatcher
├─ next.config.ts
├─ package.json
└─ tsconfig.json
```

Two things to notice about that layout. First, the middleware file is named `proxy.ts`, not `middleware.ts`. Next.js 16 [renamed the network-boundary file to `proxy.ts`](https://nextjs.org/blog/next-16) to make the boundary explicit; the CLI's starter already uses the new name. Second, the root layout uses `<Show when="signed-in">` and `<Show when="signed-out">` — the [Clerk Core 3 replacements](https://clerk.com/docs/guides/how-clerk-works/overview.md) for the older `<SignedIn>` / `<SignedOut>` components — so gated UI is correct out of the box.

The generated `proxy.ts` looks like this:

```tsx
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isPublicRoute = createRouteMatcher(['/sign-in(.*)', '/sign-up(.*)'])

export default clerkMiddleware(async (auth, request) => {
  if (!isPublicRoute(request)) {
    await auth.protect()
  }
})

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
  ],
}
```

Every route is private by default; only the sign-in and sign-up paths are public. `auth.protect()` short-circuits unauthenticated requests before they reach any server component.

`clerk init` also auto-links the generated project to a Clerk application. If you ran the command signed in, it created or attached a development instance and wrote the link to `.clerk/config.json` in the project. That is what makes the next three commands (`env pull`, `doctor`, `config`) work without any extra flags.

Switch into the new directory:

```bash
cd my-clerk-next-app
```

## 7. Link to an existing Clerk app (optional)

If you want to point the scaffolded project at an app you (or your team) already own — say, a shared staging instance — break the auto-link and create a new one:

```bash
clerk unlink
clerk link --app app_xxx
```

Get the application ID from `clerk apps list`. `clerk link` writes the chosen app back to `.clerk/config.json` so subsequent CLI commands target it. This workflow matters most on teams: every developer can scaffold locally, then `clerk link` onto the shared development instance so they all hit the same user pool, same config, same logs.

You can also skip the auto-link entirely by passing `--app app_xxx` to `clerk init` in the first place, which is the right shape for CI or scripted scaffolds.

## 8. Pull environment variables

With a linked app in place, pull the publishable and secret keys straight into `.env.local`:

```bash
clerk env pull
```

The command writes two variables:

```bash
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_…
CLERK_SECRET_KEY=sk_test_…
```

By default `clerk env pull` targets the development instance. When you are ready to ship, pull production keys instead:

```bash
clerk env pull --instance prod
```

Use `--file` to write somewhere other than `.env.local` — for example, `clerk env pull --file .env.production.local` for a Vercel deploy that expects that filename. The command is idempotent: re-running it overwrites the matched keys without touching any unrelated variables you have added to the file.

> Never commit `.env.local` or any file containing `CLERK_SECRET_KEY`. The starter's `.gitignore` already excludes `.env*.local`; keep it that way.

## 9. Run `clerk doctor` the first time (it should fail)

`clerk doctor` is the integration health check. Run it _before_ you start the dev server the first time — it catches problems the dev server would otherwise report as a stack trace on the first page load.

To see the failure shape on purpose, temporarily hide the env file and run doctor:

```bash
mv .env.local .env.local.bak
clerk doctor
```

The output flags the missing publishable key and the missing secret key as distinct failures, confirms that `ClerkProvider` is wired in `app/layout.tsx`, confirms that `clerkMiddleware` is wired in `proxy.ts`, and reports your installed `@clerk/nextjs` version. The failure is specific enough to act on: it tells you _which_ variable is missing and _where_ the CLI expects it, not just "auth is broken."

A failing `clerk doctor` is a good thing. It is faster and more legible than a runtime stack trace from the Next.js dev server, and it gives you actionable errors before you have loaded a single page.

## 10. Run `clerk doctor` after env pull (green)

Restore the env file and re-run:

```bash
mv .env.local.bak .env.local
clerk doctor
```

Every check now passes: env vars present, provider wired, middleware wired, SDK version current. `clerk doctor --spotlight` hides the passing checks and shows only failures, which is the mode you want once the project is healthy and you are only running doctor to confirm nothing has regressed.

> `clerk doctor --fix` attempts auto-remediation for the common failures — missing `ClerkProvider`, missing middleware wiring, out-of-date SDK. Inspect the diff it proposes before accepting it.

## 11. Start the dev server and sign up a test user

With doctor green, start the dev server:

```bash
pnpm dev
```

Open `http://localhost:3000`. The starter renders a header with **Sign in** and **Sign up** buttons (the `<Show when="signed-out">` branch of `app/layout.tsx`). Click **Sign up**, create a test user with email + password, verify the email code, and land back on the starter's home page — now with a `UserButton` avatar in the header (the `<Show when="signed-in">` branch).

That is a working Clerk-authed Next.js 16 app — scaffolded, keyed, and signed into — with zero dashboard clicks. Every step after this point is configuration on top of a running system.

## 12. Configure Clerk as code: `clerk config`

`clerk config` is the command that made the CLI worth shipping. Instead of clicking through dashboard toggles to enable passkeys, add sign-in methods, or change session policy, you describe the configuration in JSON and apply it through the terminal — reviewable in a pull request, versionable in git, replayable across dev and production.

### Discover the schema

Before patching anything, see what is configurable:

```bash
clerk config schema
```

The full schema is long. Narrow it to the keys you care about:

```bash
clerk config schema --keys auth_passkey session auth_access_control
```

### Pull the current state

Snapshot the current instance configuration:

```bash
clerk config pull --output config.before.json
```

`config.before.json` is a full dump of every setting Clerk currently has for the linked instance — sign-in methods, session policy, OAuth connectors, organization settings, branding. Commit it to a branch (it's not a secret; it contains no keys) and you have a versioned record of the instance.

### Patch 1 — enable passkeys

Passkeys are phishing-resistant, WebAuthn-backed credentials bound to the user's device.

> Passkeys require a paid Clerk plan. The Hobby (free) tier blocks this patch with a plan-gate error. See [pricing](https://clerk.com/pricing).

Dry-run the patch first to see the exact change the CLI will apply:

```bash
clerk config patch --dry-run --json '{"auth_passkey":{"used_for_sign_in":true}}'
```

The dry-run output prints the JSON diff against the current config without mutating anything. When you are happy with it, drop `--dry-run`:

```bash
clerk config patch --json '{"auth_passkey":{"used_for_sign_in":true}}' --yes
```

`--yes` skips the interactive confirmation so the command works in CI. Passkey sign-in is now enabled on the instance. Clerk's UI components will pick up the change on the next render — no server restart required beyond Next.js's dev HMR.

### Patch 2 — tighten sign-in security

Block disposable email domains at sign-up and lower the failed-attempt lockout threshold from the default:

```bash
clerk config patch --dry-run --json '{
  "auth_access_control": { "block_disposable_email_domains": true },
  "auth_attack_protection": {
    "user_lockout": { "max_attempts": 10 }
  }
}' --yes
```

After the dry-run confirms the diff, remove `--dry-run`. Two semantic changes in one patch: sign-ups from throwaway email services are rejected, and the lockout triggers after 10 failed attempts instead of the default 100.

### Patch 3 — strengthen the password policy

Clerk's default policy adheres to NIST 800-63B — 8-character minimum, no composition rules, HIBP (Have I Been Pwned) checks on sign-up and sign-in — which is sound out of the box. If your threat model calls for something stricter, tighten the policy so sign-ups and password resets must meet a higher bar:

> Custom password requirements are a Pro/Business feature. The Hobby (free) tier keeps the NIST defaults and blocks this patch. See [pricing](https://clerk.com/pricing).

```bash
clerk config patch --json '{
  "auth_password": {
    "min_length": 12,
    "min_zxcvbn_strength": 3,
    "require_numbers": true,
    "show_zxcvbn": true
  }
}' --yes
```

Four semantic changes: the minimum length goes from the default 8 to 12 characters, the `min_zxcvbn_strength` threshold lifts from 0 to 3 (on zxcvbn's 0-4 scale, where 3 is "safely unguessable"), passwords must contain at least one number, and Clerk's hosted UI renders a live strength meter on the password field. HIBP checks are already enforced on sign-in by default on a fresh instance — see `auth_password.enforce_hibp_on_sign_in` in the pulled config.

### Snapshot the result

Pull the new state and diff it against the original:

```bash
clerk config pull --output config.after.json
diff config.before.json config.after.json
```

You should see the expected semantic changes (plus an auto-bumped `config_version`): `auth_passkey.used_for_sign_in` went `true`, `auth_access_control.block_disposable_email_domains` went `true`, `auth_attack_protection.user_lockout.max_attempts` went `10`, and the four `auth_password` tightening fields moved from their defaults to the stricter policy. That diff is now your instance configuration change log — commit both files to the repo and the review is a normal PR.

## 13. Verify the config changes worked

Reload `http://localhost:3000`. Click **Sign in** and you should now see a passkey registration option (Clerk's SDK renders the passkey button when `auth_passkey.used_for_sign_in` is true and the browser supports [WebAuthn](https://clerk.com/glossary/webauthn.md)). Sign in with your existing test user, open **User button → Manage account → Security**, and register a passkey using your browser's built-in authenticator — Touch ID on macOS, Windows Hello on Windows, the device's screen lock on Android. The passkey is now bound to that user and can be used on any subsequent sign-in.

Try to sign up a new user with a disposable email (for example, an address at `mailinator.com`) and you should get a policy-enforced rejection from the `auth_access_control` patch. In the same sign-up flow, try a weak password like `password` — the form will reject it against the new `min_length`, `min_zxcvbn_strength`, and `require_numbers` rules, and the strength meter underneath the field reflects the `show_zxcvbn` toggle from Patch 3.

## 14. Inspect your instance with `clerk api`

`clerk api` is an authenticated terminal client for Clerk's Backend API, with key resolution and instance targeting handled automatically by the linked app.

Discover what endpoints exist:

```bash
clerk api ls
clerk api ls users
```

`clerk api ls` lists the top-level resources; `clerk api ls users` scopes to a single resource and shows the available operations.

Fetch the list of users on the instance — your test user should appear:

```bash
clerk api /users
```

Pick the user ID from the response and fetch the full user object:

```bash
clerk api /users/user_xxx
```

The response includes the `passkeys` array (populated after step 13) and the user's primary email, both of which confirm the earlier steps landed. Use the one-liner `clerk api /users/user_xxx | jq '.passkeys'` to zoom in.

For write operations, `clerk api` supports `-X POST`, `-X PATCH`, and `-X DELETE` with a `-d` payload and optional `--dry-run`. Mutations in a tutorial are a footgun, so the one you will run first in production is almost always a read: users, sessions, organizations. The [Backend API reference](https://clerk.com/docs/reference/backend-api) documents the full surface and is the right place to look before running a mutation.

Clerk also ships a separate Platform API for account-level operations (list your own applications, manage billing). Inspect it with:

```bash
clerk api --platform ls
```

Platform endpoints require platform-level credentials, which are distinct from per-application keys — `clerk api --platform` resolves them from your logged-in account rather than the linked application.

## 15. CLI reference (quick skim)

Commands covered above, plus the ones you will reach for next:

```bash
# Setup
clerk --version
clerk update                     # latest stable
clerk update --channel canary    # ride the canary train
clerk update --all               # update every clerk install on PATH
clerk completion zsh             # emit shell completion for zsh|bash|fish

# Auth
clerk auth login
clerk whoami
clerk open                       # dashboard escape hatch

# Apps
clerk apps list
clerk apps create <name>
clerk link --app app_xxx
clerk unlink

# Project
clerk init                       # integrate into current dir
clerk init --starter             # new project from template
clerk init --prompt              # emit setup instructions for agents

# Environment + diagnostics
clerk env pull [--instance prod] [--file path]
clerk doctor [--spotlight] [--fix] [--verbose]

# Config as code
clerk config schema [--keys a b c]
clerk config pull [--output file]
clerk config patch --json '...' [--dry-run] [--yes]
clerk config put --file config.json   # destructive — see warning below

# Backend API
clerk api ls [resource]
clerk api <path>
clerk api --platform ls
clerk api -X POST <path> -d '...'     # mutations; pair with --dry-run

# Agent skills
clerk skill install
```

> `clerk config put` replaces the entire instance configuration with the contents of the file. It is not additive. Use `clerk config patch` for every incremental change. Reach for `put` only when you are intentionally resetting an instance (for example, promoting a full config from staging to a new production tenant), and run it with `--dry-run` first every time.

For the full reference including per-command flags, see the canonical [CLI documentation](https://clerk.com/docs/cli.md) and the [`clerk/cli` repository](https://github.com/clerk/cli).

## FAQ

## FAQ

### Do I need the Clerk CLI to use Clerk with Next.js?

No. The `@clerk/nextjs` [SDK](https://clerk.com/glossary/software-development-kit-sdk.md) still works standalone — install the package, add `ClerkProvider`, add `clerkMiddleware`, and paste keys from the dashboard. The CLI is a faster, agent-friendly path that collapses those steps into `clerk init`, plus it adds config-as-code (`clerk config patch`) and diagnostics (`clerk doctor`) that you cannot get from the dashboard-only flow.

### Does clerk init --starter work with Next.js 16's App Router and proxy.ts?

Yes. The Next.js starter scaffolds an App Router project on `next@16.2.4` with `@clerk/nextjs@^7.2.5` and writes `proxy.ts` (not `middleware.ts`), matching Next.js 16's renamed network-boundary file. The generated `proxy.ts` exports `clerkMiddleware` with a `createRouteMatcher` public-routes pattern out of the box.

### Can I use the Clerk CLI with an existing Next.js app, or only new ones?

Both. `clerk init` without `--starter` auto-detects the framework in the current directory, installs `@clerk/nextjs`, and writes the `ClerkProvider` + middleware wiring in place. `clerk init --starter` creates a fresh project from a template instead. The docs also document a third mode — running `clerk init` without a Clerk account, which boots you with temporary development keys.

### What does clerk doctor actually check?

It validates your project's Clerk integration end-to-end: presence and shape of `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`, that `ClerkProvider` wraps the app, that `clerkMiddleware` is wired in `proxy.ts` (or `middleware.ts` on older Next versions), and that the installed `@clerk/nextjs` version is current. `--spotlight` hides passing checks; `--fix` attempts auto-remediation for the common failures.

### How is clerk config patch different from clicking through the Clerk Dashboard?

`clerk config patch` mutates your Clerk instance's auth configuration — sign-in methods, redirects, session policies, branding — from JSON you commit to a repo, so every change is code-reviewable, versionable, and scriptable from CI. The dashboard UI is still fine for exploration and one-offs; the CLI adds `--dry-run` diffs and lets you chain patches across dev, staging, and production the same way you ship database migrations.

### Is clerk api the same as calling the Backend API with curl?

Functionally yes — `clerk api` is an authenticated HTTP client for Clerk's Backend API. The CLI handles [API key](https://clerk.com/glossary/api-key.md) resolution from your linked app, auth headers, instance targeting, JSON formatting, and discovery (`clerk api ls`), so you skip the boilerplate and the risk of leaking a secret key into shell history. For programmatic production use, SDK calls are still the right choice; for exploration and scripted ops, `clerk api` is faster.

### Do passkeys require a paid Clerk plan?

Yes. Per the [pricing page](https://clerk.com/pricing), [passkeys](https://clerk.com/glossary/passkeys.md) are not included on the Hobby (free) tier — they ship on Pro and Business plans. If you run `clerk config patch --json '{"auth_passkey":{"used_for_sign_in":true}}'` against a free-tier instance, the patch is rejected at the plan gate. Keep the rest of the CLI walk-through and skip the passkey patch (or upgrade) if you're on Hobby.

### Can I run clerk config patch against production?

Yes. Pair it with the appropriate `--instance prod` flag on `clerk env pull` (and target the production application via `clerk link`) and always run `--dry-run` first to see the diff. Because each patch is a single JSON mutation against live auth configuration, treat it like a database migration: land the change in a PR, review the diff, apply on staging, then production.

### What does clerk skill install actually install?

It installs Clerk's bundled agent skills — the core `clerk` CLI operator skill, `clerk-backend-api`, and framework-specific skills like `clerk-nextjs-patterns` — into the detected scope (global `~/.claude/skills/` or project-local). The skills give AI coding agents current, version-matched Clerk context so Claude Code, Cursor, and similar harnesses generate correct imports (for example, `<Show when="signed-in">` in `@clerk/nextjs` v7 rather than the removed `<SignedIn>`) instead of hallucinating from stale training data.

### How do I switch from development keys to production keys?

Create (or link to) a production instance, then run `clerk env pull --instance prod`. This rewrites the matched variables in `.env.local` — or use `--file .env.production.local` if you keep production keys in a separate file. Pair with `clerk link --app app_prod_xxx` if the production instance lives under a different Clerk application.

### Does the CLI replace the Clerk Dashboard?

No, it complements it. The CLI covers project setup, environment, config as code, diagnostics, and Backend API access. The dashboard still owns OAuth provider client credentials, billing, analytics, and one-off exploratory edits. `clerk open` opens the linked app's dashboard from your terminal when you need it.

### Can I use the CLI inside an AI coding agent like Claude Code or Cursor?

Yes — the CLI is designed for both humans and agents. It auto-detects a non-TTY environment and switches to deterministic, parseable output; `clerk init --prompt` emits framework-specific setup instructions for the agent to execute itself; and `clerk skill install` ships Clerk-maintained skills that give the agent current, version-matched knowledge. Next.js [documents the same agent-friendly pattern](https://nextjs.org/docs/app/guides/ai-agents), and [shadcn/ui](https://ui.shadcn.com/docs/skills) uses a parallel skills model.

## Sources

- [Clerk CLI documentation](https://clerk.com/docs/cli.md)
- [Clerk CLI changelog entry (2026-04-22)](https://clerk.com/changelog/2026-04-22-clerk-cli.md)
- [Clerk: How Clerk Works — overview](https://clerk.com/docs/guides/how-clerk-works/overview.md)
- [Clerk Pricing](https://clerk.com/pricing)
- [`clerk/cli` source repository](https://github.com/clerk/cli)
- [Next.js 16 release notes](https://nextjs.org/blog/next-16)
- [Next.js AI agents guide](https://nextjs.org/docs/app/guides/ai-agents)
- [shadcn/ui skills documentation](https://ui.shadcn.com/docs/skills)