CLI Installer

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.

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.

• Node.js 20+
• A WorkOS account
• A project using one of the supported frameworks

Use the --integration flag to specify your framework manually:

npx workos@latest install --integration nextjs

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.

npx workos@latest install --debug

After the CLI completes, use git diff to review all the files it created or modified:

git diff

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