AI Installer & CLI
Integrate AuthKit with one command, manage resources, provision environments, and equip your coding agents — all from the WorkOS CLI.
Introduction
The WorkOS CLI is a comprehensive tool for integrating and managing WorkOS from the terminal. Its headline feature is the AI Installer – run one command and it handles framework detection, SDK installation, route creation, environment setup, and build validation. Beyond the installer, the CLI also manages resources, provisions environments, and equips your coding agents with WorkOS knowledge.
| npx workos@latest integrate |
| npm install -g workos && workos integrate |
Run one command, the CLI handles the rest. Your app goes from zero auth to full AuthKit integration in about two minutes. You don’t need a WorkOS account to start: without credentials, the installer creates an unclaimed environment that you can claim later.
The installer takes care of everything you would normally do manually:
- Detects your framework – Identifies your framework and version from your project’s dependencies and file structure
- Gets credentials – Uses
WORKOS_API_KEY,--api-keyor the CLI’s active environment if you have one. Otherwise it creates an unclaimed environment, with no account or sign-in needed - Configures your dashboard – Sets redirect URIs, CORS origins, and homepage URL automatically
- Installs the right SDK – Adds the correct AuthKit package for your framework
- Analyzes your project – Reads your project structure to understand routing, existing middleware, and configuration
- Creates routes and middleware – Writes OAuth callback routes, auth middleware/proxy, and provider wrappers
- Sets up environment variables – Writes API keys and configuration to
.env.local - Validates the integration – Runs your build to verify everything compiles without errors
The installer 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.
| Framework | SDK |
|---|---|
| Next.js | @workos-inc/authkit-nextjs |
| React | @workos-inc/authkit-react |
| React Router | @workos-inc/authkit-react-router |
| TanStack Start | @workos/authkit-tanstack-react-start |
| SvelteKit | @workos/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) |
The CLI uses an AI agent with restricted permissions to integrate AuthKit into your project:
- Local analysis – The agent reads your project files locally to detect frameworks and understand your project structure.
- 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.
- File modifications – The agent creates and edits files in your project to set up the AuthKit integration. Use
git diffafter installation to review every change. - Dashboard configuration – The CLI configures your WorkOS environment’s settings (redirect URIs, CORS) with the credentials from step 2.
When the installer finds no WorkOS credentials (no WORKOS_API_KEY or --api-key, no active CLI environment with an API key, and no key in your project’s .env.local or .env), it provisions an unclaimed environment instead of asking you to sign in. This also works for coding agents, which can run the installer without a human.
- It works right away. The environment is a real WorkOS environment with a full-scope API key. The installer writes
WORKOS_API_KEY,WORKOS_CLIENT_IDandWORKOS_CLAIM_TOKENto your project’s.env.localor.env. - It’s temporary until you claim it. The CLI also keeps the claim token on this machine. Keep
WORKOS_CLAIM_TOKEN: without it, the environment can’t be claimed. - Claim it when you’re ready. Run
npx workos@latest profile claim. It opens the WorkOS dashboard, where you sign in or create an account and confirm. Claiming links the environment to your account permanently, and your app keeps the same credentials.
To get credentials without changing any code, for example from a coding agent, run npx workos@latest env provision. It prints the API key and client ID and makes the new environment active in the CLI, but never writes to your project.
If you installed the CLI globally, drop the npx workos@latest prefix and run workos profile claim or workos env provision. The CLI’s own messages use that short form.
If you already have a WorkOS account, set WORKOS_API_KEY or pass --api-key to install into one of your existing environments instead.
| Flag | Description |
|---|---|
--redirect-uri <uri> |
Custom OAuth callback URI (default: http://localhost:3000/callback) |
--no-validate |
Skip post-install build validation |
--debug |
Verbose logging for troubleshooting |
Install WorkOS knowledge directly into your AI coding agent so it understands AuthKit when helping you write code. Skills give agents context about WorkOS APIs, SDKs, and integration patterns – so they produce correct integration code without you having to explain WorkOS concepts.
Supported agents:
| Agent | Skills directory |
|---|---|
| Claude Code | ~/.claude/skills |
| Codex | ~/.codex/skills |
| Cursor | ~/.cursor/skills |
| Goose | ~/.config/goose/skills |
Use workos skills list to see available and installed skills, and workos skills uninstall to remove them.
The CLI provides full CRUD operations for WorkOS resources directly from the terminal – organizations, users, roles, permissions, connections, directories, webhooks, vault secrets, feature flags, and more.
All resource commands support --json for scripting and CI pipelines. In non-TTY environments (pipes, CI runners, coding agents), JSON output is enabled automatically.
Define your permissions, roles, organizations, and config in a YAML file and provision them in one command. The CLI tracks state so you can tear everything down cleanly with --clean.
| Command | Description |
|---|---|
workos setup-org <name> |
Create an org with optional domain verification, roles, and Admin Portal link |
workos onboard-user <email> |
Send an invitation with optional role assignment – use --wait to poll until acceptance |
workos debug-sso <connectionId> |
Inspect SSO connection state and recent auth event history |
workos debug-sync <directoryId> |
Inspect directory sync state, user/group counts, and detect stalls |
Manage multiple WorkOS environments, switch between them, and authenticate – all from the terminal.
Use workos env switch to change environments and workos env add to configure new ones. Run workos doctor to diagnose integration issues in the current project – it checks your SDK version, environment configuration, connectivity, dashboard settings, and auth patterns.
- Node.js 20+
- A project using one of the supported frameworks (for the AI installer)
The installer detects your framework from the project files, so run it from the project root. Confirm your framework is one of the supported frameworks. For a Next.js project where the router is ambiguous, pass --router app or --router pages:
Run the installer with --debug for detailed output. Make sure your project builds cleanly before running the installer – pre-existing build errors will cause validation to fail.
After the installer completes, use git diff to review all the files it created or modified:
Run workos doctor to diagnose common issues. If the problem persists, open an issue on GitHub with the output from --debug mode.
- Sessions – Understand session management
- Branding – Customize the AuthKit UI
- Example Apps – View complete working examples
- Quick Start – Manual integration guide for full control