---
title: CLI Installer
description: >-
Add AuthKit to your project in minutes with a single command. The WorkOS CLI
uses AI to detect your framework, install the right SDK, and write the
integration code automatically.
showNextPage: true
originalPath: .tmp-workos-clone/packages/docs/content/authkit/cli-installer.mdx
---
## Introduction {{ "visibility": "no-quick-nav" }}
Run one command, the CLI handles the rest: framework detection, SDK installation, route creation, environment setup, and build validation. Your app goes from zero auth to full AuthKit integration in about two minutes.
```bash
$ npx workos@latest install
◆ Detected Next.js 15.3.1 (App Router)
│
◇ Opening browser for WorkOS authentication...
│ Authenticated as nick@example.com
│
◇ Configuring your WorkOS dashboard...
│ ✓ Redirect URI set to http://localhost:3000/callback
│ ✓ Homepage URL set to http://localhost:3000
│
◇ Installing @workos-inc/authkit-nextjs...
│ ✓ Package installed
│
◇ Analyzing project structure...
│ ✓ Created /app/callback/route.ts
│ ✓ Created proxy.ts
│ ✓ Updated /app/layout.tsx with AuthKitProvider
│ ✓ Created .env.local
│
◇ Validating integration...
│ ✓ Build completed successfully
│
◆ AuthKit is ready. Run `npm run dev` to get started.
```
> Prefer to configure things yourself? Follow the [Quick Start](/authkit) guide instead.
---
## What the CLI handles
The CLI takes care of everything you would normally do manually:
1. **Detects your framework** — Identifies your framework and version from your project's dependencies and file structure
2. **Authenticates your account** — Opens your browser for secure WorkOS sign-in
3. **Configures your dashboard** — Sets redirect URIs, CORS origins, and homepage URL automatically
4. **Installs the right SDK** — Adds the correct AuthKit package for your framework
5. **Analyzes your project** — Reads your project structure to understand routing, existing middleware, and configuration
6. **Creates routes and middleware** — Writes OAuth callback routes, auth middleware/proxy, and provider wrappers
7. **Sets up environment variables** — Writes API keys and configuration to `.env.local`
8. **Validates the integration** — Runs your build to verify everything compiles without errors
The CLI understands framework-specific nuances — like Next.js App Router vs Pages Router, Vite vs Create React App, and React Router nuances — and generates the appropriate code for your setup. If you have existing middleware or configuration, it composes with it rather than replacing it.
---
## Supported frameworks
| Framework | SDK |
| ----------------------- | ------------------------------------ |
| **Next.js** | `@workos-inc/authkit-nextjs` |
| **React** | `@workos-inc/authkit-react` |
| **React Router** | `@workos-inc/authkit-react-router` |
| **TanStack Start** | `@workos-inc/authkit-tanstack-start` |
| **SvelteKit** | `@workos-inc/authkit-sveltekit` |
| **Node.js / Express** | `@workos-inc/node` |
| **Vanilla JS** | `workos` |
| **Python / Django** | `workos` (pip) |
| **Ruby / Rails** | `workos` (gem) |
| **Go** | `github.com/workos/workos-go` |
| **PHP** | `workos/workos-php` |
| **PHP / Laravel** | `workos/workos-php-laravel` |
| **.NET / ASP.NET Core** | `WorkOS.net` |
| **Kotlin** | `com.workos:workos-kotlin` |
| **Elixir / Phoenix** | `workos` (hex) |
---
## How the installer works
The CLI uses an AI agent with restricted permissions to integrate AuthKit into your project:
1. **Local analysis** — The agent reads your project files locally to detect frameworks and understand your project structure.
2. **Restricted execution** — The agent can only run a limited set of commands: package installation, builds, type-checking, and formatting. It cannot run arbitrary shell commands.
3. **File modifications** — The agent creates and edits files in your project to set up the AuthKit integration. Use `git diff` after installation to review every change.
4. **Dashboard configuration** — The CLI configures your WorkOS dashboard settings (redirect URIs, CORS) using your authenticated session.
---
## Prerequisites
- Node.js 20+
- A [WorkOS account](https://dashboard.workos.com)
- A project using one of the [supported frameworks](#supported-frameworks)
---
## CLI options
| Flag | Description |
| ---------------------- | --------------------------------------------------------------------- |
| `--integration ` | Skip auto-detection and specify your framework manually |
| `--redirect-uri ` | Custom OAuth callback URI (default: `http://localhost:3000/callback`) |
| `--no-validate` | Skip post-install build validation |
| `--debug` | Verbose logging for troubleshooting |
---
## Troubleshooting
### The CLI didn't detect my framework
Use the `--integration` flag to specify your framework manually:
```bash
npx workos@latest install --integration nextjs
```
### Build validation failed
Run the CLI with `--debug` for detailed output. Make sure your project builds cleanly before running the CLI — pre-existing build errors will cause validation to fail.
```bash
npx workos@latest install --debug
```
### I want to see what changed
After the CLI completes, use `git diff` to review all the files it created or modified:
```bash
git diff
```
### Something else went wrong
Run `workos doctor` to diagnose common issues. If the problem persists, [open an issue on GitHub](https://github.com/workos/cli/issues) with the output from `--debug` mode.
---
## What's next
- [Sessions](/authkit/sessions) — Understand session management
- [Branding](/authkit/branding) — Customize the AuthKit UI
- [Example Apps](/authkit/example-apps) — View complete working examples
- [Quick Start](/authkit) — Manual integration guide for full control