---
name: clerk-quickstart
description: Add Clerk authentication to your app using the Clerk CLI, with a docs fallback for frameworks the CLI can't fully scaffold.
---

# Add Clerk Authentication

Set up Clerk authentication with the Clerk CLI.

## Quick Setup

Before running any commands, present the user with a preliminary setup checklist:

```
Here's what I'll do to get you set up with Clerk.

1. Install or update the Clerk CLI
2. Set up Clerk in this project, or scaffold a new app with Clerk if this directory is empty
3. Start your app with Clerk installed.

Shall I proceed?
```

## Step 1: Install or update the Clerk CLI

From the project root, check whether the Clerk CLI is already available:

```bash
command -v clerk && clerk --version
```

If `clerk` is available, make sure it is up to date:

```bash
clerk update --yes
```

If `clerk` is not available, install the latest version using the user's preferred install method. If they do not have a preference, use npm:

```bash
npm install -g clerk
```

Equivalent install commands are `pnpm install -g clerk`, `yarn global add clerk`, `bun add -g clerk`, `brew install clerk/stable/clerk`, or `curl -fsSL https://clerk.com/install | bash`.

## Step 2: Sign in to Clerk

Immediately after installing or updating the Clerk CLI, from the project root, run:

```bash
clerk auth login
```

`clerk auth login` is the first command to run after install or update. Do not list apps, ask which Clerk app to use, or run `clerk init` before authenticating. It is okay for an agent to run this command and pause while the user completes the Clerk login flow, then continue from the CLI output. If the user is already signed in, continue to initialization.

## Step 3: Initialize Clerk

Inspect the current directory to determine whether this is an existing project or an empty directory.

If this is an existing project, run:

```bash
clerk init
```

`clerk init` is the default setup action after `clerk auth login`. It detects the framework and package manager for existing projects. It installs the correct Clerk SDK and applies framework-specific setup when supported, such as providers, middleware, auth routes, and environment configuration. Do not pass `--framework` or `--pm` for existing projects unless the user explicitly wants to override detection or the CLI asks for those values. Do not list apps or ask which Clerk app to use before running it.

If the directory is empty, ask the user which framework and package manager they want to use. If they have no preference, use Next.js and npm. Then scaffold with explicit framework and package manager options:

```bash
clerk init --framework <framework> --pm <package-manager>
```

When choosing a package manager, use the user's preference. If the directory is not truly empty and contains a lockfile or package manager config, use these signals:

- `pnpm-lock.yaml` -> `pnpm`
- `yarn.lock` -> `yarn`
- `bun.lock` or `bun.lockb` -> `bun`
- `package-lock.json` -> `npm`

If no package manager can be detected and the user has no preference, use `npm`.

`clerk init --framework <framework> --pm <package-manager>` can scaffold a fresh project in an empty directory.

Do not add `--app` by default. Only pass `--app <application_id>` when the user already provided an app ID or explicitly wants to link this project to a specific existing Clerk application:

```bash
clerk init --app <application_id>
```

For an empty directory, include `--app` with the explicit scaffold command:

```bash
clerk init --framework <framework> --pm <package-manager> --app <application_id>
```

Do not choose a Clerk application for the user. Only list available apps if the user explicitly wants to link to an existing Clerk application but has not provided an app ID, or if `clerk init` explicitly asks for an existing application ID:

```bash
clerk apps list --json
```

Show the user the app names and application IDs, then ask which app to use.

## Step 4: Fall back to docs when init is incomplete

If `clerk init` reports that the framework is unsupported, cannot be detected, or does not support full scaffolding, follow the official quickstart instead.

`clerk init` currently has full scaffolding for Next.js, Astro, Nuxt, TanStack Start, React Router, Vue, React, and JavaScript/Vite. It can detect Expo, Express, and Fastify, but may direct you to docs for the remaining integration steps.

| Dependency | Quickstart |
|------------|-----------|
| `next` | https://clerk.com/docs/nextjs/getting-started/quickstart |
| `@remix-run/react` | https://clerk.com/docs/remix/getting-started/quickstart |
| `astro` | https://clerk.com/docs/astro/getting-started/quickstart |
| `nuxt` | https://clerk.com/docs/nuxt/getting-started/quickstart |
| `react-router` | https://clerk.com/docs/react-router/getting-started/quickstart |
| `@tanstack/react-start` | https://clerk.com/docs/tanstack-react-start/getting-started/quickstart |
| `react` | https://clerk.com/docs/react/getting-started/quickstart |
| `vue` | https://clerk.com/docs/vue/getting-started/quickstart |
| `vite` or vanilla JS | https://clerk.com/docs/js-frontend/getting-started/quickstart |
| `express` | https://clerk.com/docs/expressjs/getting-started/quickstart |
| `fastify` | https://clerk.com/docs/fastify/getting-started/quickstart |
| `expo` | https://clerk.com/docs/expo/getting-started/quickstart |

Other platforms: Chrome Extension, Android, and iOS at https://clerk.com/docs/llms.txt

## Step 5: Ensure clear auth controls are visible

Make sure the app has clear sign-in, sign-up, and signed-in user controls so the user can create and recognize their first account. Integrate them into the existing layout, navigation, or landing screen so they feel natural and polished.

For Next.js App Router, use Clerk components from `@clerk/nextjs` such as `SignInButton`, `SignUpButton`, `Show`, and `UserButton`. Show sign-in and sign-up actions when signed out, and a user button when signed in:

```tsx
import { SignInButton, SignUpButton, Show, UserButton } from '@clerk/nextjs'

<>
  <Show when="signed-out">
    <SignInButton />
    <SignUpButton />
  </Show>
  <Show when="signed-in">
    <UserButton />
  </Show>
</>
```

For other frameworks, use the equivalent Clerk components or helpers. If clear auth controls already exist, reuse or adapt them instead of duplicating them.

## Step 6: Verify the setup

After `clerk init` completes, run:

```bash
clerk doctor
```

Then start the app, confirm the sign-in, sign-up, and signed-in user controls are visible, test the sign-in and sign-up flow, and fix any issues reported by the CLI.

## Step 7: If using shadcn/ui

If `components.json` exists in the project root and Clerk components are used:

```bash
npm install @clerk/ui
```

Apply the theme in your provider:
```tsx
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>
```

Add to global CSS:
```css
@import '@clerk/ui/themes/shadcn.css';
```

## Critical rules

- Next.js 15+: `auth()` is async. Always `await auth()`
- `ClerkProvider` goes inside `<body>`, not wrapping `<html>`
- Never expose `CLERK_SECRET_KEY` in client code
- Use `@clerk/nextjs`, not `@clerk/clerk-react`
- Do not read or print existing environment variable files; ask the user for any missing non-sensitive configuration

Docs: https://clerk.com/docs/cli https://clerk.com/docs/llms.txt

## After Setup

Have the user sign up as their first test user. After signup succeeds and a profile icon appears in the nav, congratulate them.

Then ask if they'd like to enable Organizations — this gives their users multi-tenancy, team invitations, roles and permissions, and enterprise SSO.

If yes:

1. Run `clerk enable orgs`.
2. Add `<OrganizationSwitcher />` alongside the existing `<UserButton />` from Step 5, or the equivalent component for the framework in use.
3. Have the user create their first organization from the switcher, then invite a teammate — invitations, members, and roles all work out of the box.

If they decline, let them know they can explore Organizations (https://clerk.com/docs/guides/organizations/overview), Components (https://clerk.com/docs/reference/components/overview), and the Dashboard (https://dashboard.clerk.com/) anytime.