AI-powered CLI that automatically integrates WorkOS AuthKit into web applications.
# Run directly with npx (recommended)
npx @workos/installer
# Or install globally
npm install -g @workos/installer
workos-installer- 5 Framework Support: Next.js, React Router, TanStack Start, React SPA, Vanilla JS
- AI-Powered: Uses Claude to intelligently adapt to your project structure
- Security-First: Masks API keys, redacts from logs, saves to .env.local
- Smart Detection: Auto-detects framework, package manager, router type
- Live Documentation: Fetches latest SDK docs from WorkOS and GitHub
- Full Integration: Creates routes, middleware, environment vars, and UI
Depending on your framework, the wizard creates:
- ✅ Authentication routes (callback, sign-in, sign-out)
- ✅ Middleware for route protection
- ✅ Environment variable configuration
- ✅ SDK installation with correct package manager
- ✅ UI components showing login status
- ✅ User info display (name, email)
Get your credentials from dashboard.workos.com:
- API Key (sk_test_xxx or sk_live_xxx) - For server-side frameworks only
- Client ID (client_xxx) - Required for all frameworks
Security: API keys are masked during input and redacted in logs.
workos-installer [options] [command]
Commands:
dashboard Run with visual TUI dashboard (experimental)
login Authenticate with WorkOS via Connect OAuth device flow
logout Remove stored credentials
install-skill Install AuthKit skills to coding agents (Claude Code, Codex, etc.)
Options:
--integration <name> Framework: nextjs, react, react-router, tanstack-start, vanilla-js
--api-key <key> WorkOS API key (masked in terminal)
--client-id <id> WorkOS Client ID
--redirect-uri <uri> Custom redirect URI (defaults to framework convention)
--homepage-url <url> Custom homepage URL (defaults to http://localhost:{port})
--ci Non-interactive CI mode
--install-dir <path> Installation directory
--debug Verbose logging to /tmp/wizard.log
--local Use local LLM gateway (development only)
--default Use default options for all prompts (default: true)
--skip-auth Skip authentication check (requires --local)
Environment Variables:
WIZARD_TELEMETRY=false Disable telemetry collection# Interactive (recommended)
npx @workos/installer
# Specify framework
npx @workos/installer --integration react-router
# CI mode
npx @workos/installer --ci \
--integration nextjs \
--api-key $WORKOS_API_KEY \
--client-id $WORKOS_CLIENT_IDThe wizard uses WorkOS Connect OAuth device flow for authentication:
# Login (opens browser for authentication)
workos-installer login
# Logout (clears stored credentials)
workos-installer logoutCredentials are stored in ~/.wizard/credentials.json. Access tokens are not persisted long-term for security - users re-authenticate when tokens expire.
- Detects your framework and project structure
- Prompts for WorkOS credentials (API key masked)
- Auto-configures WorkOS dashboard (redirect URI, CORS, homepage URL)
- Fetches latest SDK documentation from workos.com
- Uses AI (Claude) to generate integration code
- Installs SDK with detected package manager
- Creates auth routes, middleware, and UI
- Configures environment variables securely
The wizard collects anonymous usage telemetry to help improve the product:
- Session outcome (success/error/cancelled)
- Framework detected
- Duration and step timing
- Token usage (for capacity planning)
No code, credentials, or personal data is collected. Disable with:
WIZARD_TELEMETRY=false npx @workos/installerDetailed logs (with redacted credentials) are saved to:
/tmp/wizard.log
Use --debug flag for verbose terminal output.
See DEVELOPMENT.md for development setup.
Build:
pnpm buildRun locally:
pnpm dev # Watch mode
./dist/bin.js --helpMIT © WorkOS