npx workos: コードベースに直接認証を書き込むAIエージェント

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.

JavaScript

AI Installer

Run one command, the CLI handles the rest. Your app goes from zero auth to full AuthKit integration in about two minutes.

What the installer handles

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

• Authenticates your account – Opens your browser for secure WorkOS sign-in

• 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.

Supported frameworks

FrameworkSDK

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 JSworkos

Python / Djangoworkos (pip)

Ruby / Railsworkos (gem)

Gogithub.com/workos/workos-go

PHPworkos/workos-php

PHP / Laravelworkos/workos-php-laravel

.NET / ASP.NET CoreWorkOS.net

Kotlincom.workos:workos-kotlin

Elixir / Phoenixworkos (hex)

How the installer works

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 diff after installation to review every change.

• Dashboard configuration – The CLI configures your WorkOS dashboard settings (redirect URIs, CORS) using your authenticated session.

Install options

FlagDescription

--integration <name>Skip auto-detection and specify your framework manually

--redirect-uri <uri>Custom OAuth callback URI (default: http://localhost:3000/callback)

--no-validateSkip post-install build validation

--debugVerbose logging for troubleshooting

Coding agent skills

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:

AgentSkills 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.

Manage resources

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.

Workflow commands

Compound commands that compose multiple API calls for common tasks.

Declarative provisioning with seed

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.

workos-seed.yaml

Other workflow commands

CommandDescription

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

Environments

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.

Troubleshooting

The installer didn’t detect my framework

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

Build validation failed

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.

I want to see what changed

<path d="M3.6893 6.37529C3.88335 6.24731 4.14742 6.26897 4.31821 6.43975C4.51323 6.63496 4.51323 6.95156 4.31821 7.14678L3.69907 7.76592C3.37878 8.08621 3.20737 8.25925 3.09751 8.39092L3.00473 8.51201C2.54529 9.18833 2.53677 10.0437 2.95395 10.679L3.03891 10.7933C3.14049 10.9167 3.30254 11.0803 3.61118 11.389C4.02302 11.8008 4.17689 11.9514 4.32114 12.0462L4.44223 12.1194C5.06223 12.4608 5.85391 12.4263 6.48813 11.9954L6.60923 11.9026C6.74094 11.7927 6.91473 11.6216 7.2352 11.3011L7.85337 10.6819C8.04855 10.4869 8.36517 10.487 8.5604 10.6819C8.7556 10.8771 8.75548 11.1937 8.5604 11.389L7.94223 12.0081C7.64648 12.3039 7.43399 12