gem-hunter

WorkOS CLI for installing AuthKit integrations and managing WorkOS resources.

The CLI is distributed as a standalone executable from GitHub Releases. It does not require Node.js, Bun, or an npm installation. The first agent-driven command (e.g. workos install) performs a one-time, checksum-verified download of the Claude agent runtime (~230 MB, cached under ~/.workos).

Homebrew (macOS and Linux):

brew install workos/tap/workos

macOS and Linux (direct download):

case "$(uname -m)" in
  arm64|aarch64) arch=arm64 ;;
  x86_64) arch=x64 ;;
  *) echo "Unsupported architecture: $(uname -m)"; exit 1 ;;
esac
case "$(uname -s)" in
  Darwin) os=darwin ;;
  Linux) os=linux ;;
  *) echo "Unsupported operating system: $(uname -s)"; exit 1 ;;
esac
libc=""
if [ "$os" = "linux" ] && ldd --version 2>&1 | grep -qi musl; then libc="-musl"; fi
curl -fL "https://github.com/workos/cli/releases/latest/download/workos-${os}-${arch}${libc}" -o workos
# Alpine only: the musl build needs the C++ runtime: apk add libstdc++ libgcc
chmod +x workos
sudo mv workos /usr/local/bin/workos

Windows (PowerShell):

$arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'x64' }
Invoke-WebRequest "https://github.com/workos/cli/releases/latest/download/workos-windows-$arch.exe" -OutFile workos.exe

Move workos.exe to a directory on your PATH, then run workos install. (If you already have Node.js, the npm install below works on Windows too.)

npm (thin launcher that installs the same prebuilt binary for your platform):

npm install -g workos
# or run without installing:
npx workos@latest install

• 15 Framework Support: Next.js, React Router, TanStack Start, React SPA, Vanilla JS, SvelteKit, Node.js (Express), Python (Django), Ruby (Rails), Go, .NET (ASP.NET Core), Kotlin (Spring Boot), Elixir (Phoenix), PHP (Laravel), PHP
• 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
• Greenfield Scaffolding: Run in an empty directory to scaffold a new Next.js app (via create-next-app) before wiring AuthKit
• Live Documentation: Fetches latest SDK docs from WorkOS and GitHub
• Full Integration: Creates routes, middleware, environment vars, and UI
• Agent & CI Ready: Non-TTY auto-detection, JSON output, structured errors, headless installer with NDJSON streaming

Depending on your framework, the installer 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 [command]

Commands:
  install                Install WorkOS AuthKit into your project
  auth                   Manage authentication (login, logout, status)
  env                    Manage environment configurations (add, remove, switch, list, claim)
  doctor                 Diagnose WorkOS integration issues
  skills                 Manage WorkOS skills for coding agents (install, uninstall, list)
  mcp                    Manage the WorkOS MCP server in coding agents
  setup                  Set up WorkOS skills and the MCP server

Nothing is installed into your coding agents without explicit opt-in. The CLI never silently writes skills or MCP configuration into ~/.claude, ~/.cursor, etc. After workos login or workos install, an interactive session may offer to set up your agents — the prompt defaults to No, and declining (or running non-interactively) installs nothing. To opt in at any time:

workos setup            # interactive setup (skills + MCP server)
workos setup --yes      # non-interactive opt-in
workos skills install   # skills only
workos mcp install      # MCP server only

Use workos skills list to check skill status, workos mcp status to check whether the server definition is configured, or workos doctor --fix to refresh stale skills you previously installed.

MCP configuration and OAuth authentication are separate states. The WorkOS CLI never inspects a coding agent's credentials, so "configured" means the server definition is in place — it cannot prove that OAuth is usable in any agent. Each agent owns its own OAuth; with Codex, for example, complete or refresh it with codex mcp login workos in your normal host shell. See the WorkOS MCP setup and recovery guide for user-global and trusted-project-only configuration.

Resource Management:
  organization (org)     Manage organizations
  user                   Manage users
  role                   Manage roles (RBAC)
  permission             Manage permissions (RBAC)
  membership             Manage organization memberships
  invitation             Manage user invitations
  session                Manage user sessions
  connection             Manage SSO connections
  directory              Manage directory sync
  event                  Query events
  audit-log              Manage audit logs
  feature-flag           Manage feature flags
  webhook                Manage webhooks
  config                 Manage redirect URIs, CORS, homepage URL
  authkit                Manage AuthKit app config (redirect URIs, CORS, logout URIs)
  branding               Manage branding images (logo, icon, favicon)
  portal                 Generate Admin Portal links
  vault                  Manage encrypted secrets
  api-key                Manage per-org API keys
  org-domain             Manage organization domains

Migrations:
  migrations             Migrate users and SSO connections into WorkOS

Local Development:
  emulate                Start a local WorkOS API emulator

Workflows:
  seed                   Declarative resource provisioning from YAML
  setup-org              One-shot organization onboarding
  onboard-user           Send invitation and assign role
  debug-sso              Diagnose SSO connection issues
  debug-sync             Diagnose directory sync issues

All management commands support --json for structured output (auto-enabled in non-TTY). Still-REST commands (connection, directory, audit-log, api-key, vault, workos api, and the workflow/debug commands) also accept --api-key to override the active environment's key; the other resource commands authenticate with your workos auth login session (see Resource Management).

When you run workos install without credentials, the CLI automatically provisions a temporary WorkOS environment — no account needed. This lets you try AuthKit immediately.

# Install with zero setup — environment provisioned automatically
workos install

# Check your environment
workos profile list
# Shows: unclaimed (unclaimed) ← active

# Claim the environment to link it to your WorkOS account
workos profile claim

Management commands work on unclaimed environments with a warning reminding you to claim.

The compound workflow commands compose multiple API calls into common operations. These are the highest-value commands for both developers and AI agents.

Provision permissions, roles, organizations, and config from a YAML file. Tracks created resources for clean teardown.

# Apply a seed file
workos seed --file workos-seed.yml

# Tear down everything the seed created (reads .workos-seed-state.json)
workos seed --clean

Example workos-seed.yml:

permissions:
  - name: Read Posts
    slug: posts:read
  - name: Write Posts
    slug: posts:write

roles:
  - name: Editor
    slug: editor
    permissions: [posts:read, posts:write]
  - name: Viewer
    slug: viewer
    permissions: [posts:read]

organizations:
  - name: Acme Corp
    domains: [acme.com]

config:
  redirect_uris:
    - http://localhost:3000/callback
  cors_origins:
    - http://localhost:3000
  homepage_url: http://localhost:3000

Resources are created in dependency order (permissions → roles → organizations → config). State is tracked in .workos-seed-state.json so --clean removes exactly what was created.

Creates an organization with optional domain verification, roles, and an Admin Portal link in a single command.

# Minimal: just create the org
workos setup-org "Acme Corp"

# Full: org + domain + roles + portal link
workos setup-org "Acme Corp" --domain acme.com --roles admin,viewer

Sends an invitation to a user with an optional role assignment. With --wait, polls until the invitation is accepted.

# Send invitation
workos onboard-user alice@acme.com --org org_01ABC123

# Send with role and wait for acceptance
workos onboard-user alice@acme.com --org org_01ABC123 --role admin --wait

Inspects an SSO connection's state and recent authentication events. Flags inactive connections and surfaces auth event history for debugging.

workos debug-sso conn_01ABC123

Inspects a directory's sync state, user/group counts, recent events, and detects stalled syncs.

workos debug-sync directory_01ABC123

Migrate users and SSO connections from other identity providers into WorkOS. The migrations namespace passes through to @workos/migrations.

# Interactive migration wizard
workos migrations wizard

# Export a blank CSV template
workos migrations export-template saml_connections --output saml_connections.csv
workos migrations export-template oidc_connections --output oidc_connections.csv

# Export from Auth0
workos migrations export-auth0 --domain your-tenant.auth0.com --client-id <id> --client-secret <secret>

# Import users from CSV
workos migrations import --csv users.csv

Run workos migrations --help for all available subcommands.

Start a local WorkOS API emulator. The command is backed by @workos/emulate; the standalone package binary is workos-emulate.

# Start with defaults (port 4100)
workos emulate

# CI-friendly: JSON output, custom port
workos emulate --port 9100 --json

# Pre-load seed data
workos emulate --seed workos-emulate.config.yaml

# Show login pages for SSO/AuthKit browser testing
workos emulate --interactive

workos profile add [name] [apiKey]   # Add environment (interactive if no args)
workos profile remove <name>         # Remove an environment
workos profile switch [name]         # Switch active environment
workos profile list                  # List environments with active indicator

API keys are stored in the system keychain via @napi-rs/keyring, with a JSON file fallback at ~/.workos/config.json.

All resource commands follow the same pattern: workos <resource> <action> [args] [--options].

Most resource commands — organization, user, role, permission, membership, invitation, session, event, feature-flag, org-domain, portal, webhook, config, authkit, branding — authenticate with your WorkOS dashboard session from workos auth login and target the active environment (see workos profile). Pass --environment-id <id> on any of them to target a different environment for a single invocation. Access tokens refresh automatically while the session is valid, so a logged-in machine keeps working headlessly; a dead session exits with code 4.

The remaining commands (connection, directory, audit-log, api-key, vault) still use the REST plane, as does the raw escape hatch workos api. Those resolve an API key via: --api-key flag → WORKOS_API_KEY env var → active environment's stored key.

workos organization create <name> [domain:state ...]
workos organization update <orgId> <name> [domain] [state]
workos organization get <orgId>
workos organization list [--domain] [--limit] [--before] [--after] [--order]
workos organization delete <orgId> [--yes]

workos user get <userId>
workos user list [--email] [--limit] [--before] [--after] [--order]
workos user update <userId> [--first-name] [--last-name] [--email] [--locale] [--external-id]
workos user delete <userId> [--yes]

Role mutations change the privilege surface; non-interactive callers must pass --yes.

workos role list [--org <orgId>]
workos role get <slug> [--org <orgId>]
workos role create --slug <slug> --name <name> [--description] [--org <orgId>] [--yes]
workos role update <slug> [--name] [--description] [--org <orgId>] [--yes]
workos role delete <slug> --org <orgId> [--yes]
workos role set-permissions <slug> --permissions <slugs> [--org <orgId>] [--yes]
workos role add-permission <slug> <permissionSlug> [--org <orgId>] [--yes]
workos role remove-permission <slug> <permissionSlug> --org <orgId> [--yes]

workos permission list
workos permission get <slug>
workos permission create --slug <slug> --name <name> [--description] [--yes]
workos permission update <slug> [--name] [--description] [--yes]
workos permission delete <slug> [--yes]

--org and --user are mutually exclusive on list; pagination flags apply to --org listings only.

workos membership list (--org <orgId> | --user <userId>) [--limit] [--before] [--after] [--order]
workos membership get <id>
workos membership create --org <orgId> --user <userId> [--role]
workos membership update <id> [--role] [--yes]
workos membership delete <id> [--yes]
workos membership deactivate <id> [--yes]
workos membership reactivate <id>

workos invitation list [--org] [--email] [--limit] [--before] [--after]
workos invitation get <id>
workos invitation send --email <email> [--org] [--role] [--expires-in-days]
workos invitation revoke <id> [--yes]
workos invitation resend <id>

workos session list <userId> [--limit] [--before] [--after]
workos session revoke <sessionId> [--yes]

workos connection list [--org] [--type] [--limit]
workos connection get <id>
workos connection create --org <orgId> [--name] [--external-id] [--type] [--data <json>] [--file <path|->]
workos connection update <id> [--name] [--external-id] [--type] [--data <json>] [--file <path|->]
workos connection delete <id> [--force]

connections is accepted as an alias for connection. For create and update, pass nested fields such as saml_options, oidc_options, and attribute_maps as a JSON body via --data, --file <path>, or --file - (stdin); field flags override matching top-level JSON fields. Creating and updating connections requires the Connections API migration capabilities to be enabled for your team — contact WorkOS support to enable them.

workos directory list [--org] [--limit]
workos directory get <id>
workos directory delete <id> [--force]
workos directory list-users [--directory] [--group] [--limit]
workos directory list-groups --directory <id> [--limit]

workos event list --events <types> [--range-start] [--range-end] [--after] [--limit]

workos audit-log create-event <orgId> --action <action> --actor-type <type> --actor-id <id> [--file <json>]
workos audit-log export --org <orgId> --range-start <date> --range-end <date> [--actions] [--actor-names]
workos audit-log list-actions
workos audit-log get-schema <action>
workos audit-log create-schema <action> --file <schema.json>
workos audit-log get-retention <orgId>

workos feature-flag list [--limit] [--before] [--after] [--order]
workos feature-flag get <slug>
workos feature-flag enable <slug>
workos feature-flag disable <slug>
workos feature-flag add-target <slug> <targetId>
workos feature-flag remove-target <slug> <targetId>

workos webhook list
workos webhook create --url <endpoint> --events <types>
workos webhook delete <id> [--yes]

workos config redirect add <uri>
workos config cors add <origin>
workos config homepage-url set <url>

config adds a single entry to a list. To replace a whole list, use authkit below.

Per-environment AuthKit app configuration. Unlike config, these setters replace the entire list, and each accepts --dry-run to validate without saving.

workos authkit redirect-uris list [--limit]
workos authkit redirect-uris set --uri <uri> [--uri <uri> ...] [--default <uri>] [--dry-run]
workos authkit cors get
workos authkit cors set --origin <origin> [--origin <origin> ...] [--dry-run]
workos authkit logout-uris list [--limit]
workos authkit logout-uris set --uri <uri> [--uri <uri> ...] [--default <uri>] [--dry-run]

Wildcard web origins are rejected — an accepted * would allow every browser origin, which is equivalent to disabling CORS.

The logo, icon, and favicon an environment renders, each with a light and dark variant. Branding is not AuthKit-only: the same record drives hosted AuthKit pages and transactional emails.

workos branding get
workos branding set <slot> <file>
workos branding set [--logo] [--logo-dark] [--icon] [--icon-dark] [--favicon] [--favicon-dark]

Slots are logo, logo-dark, icon, icon-dark, favicon, and favicon-dark. Set one image positionally, or several at once with the matching flags — the two forms cannot be combined in a single invocation.

# One image
workos branding set icon ./icon.png

# Several at once
workos branding set --logo ./logo.png --logo-dark ./logo-dark.png --favicon ./favicon.ico

Images must be under 400 KB each and one of .png, .jpg, .jpeg, .gif, .svg, .webp, .avif, or .ico. Only the images you name are changed; the rest are left as they are. There is no way to clear an image from the CLI — upload a replacement instead.

workos portal generate-link --intent <intent> --org <orgId>

Supported intents: sso, dsync, log_streams, domain_verification, certificate_renewal. Generating a link expires prior links of the same intent.

workos vault list [--limit]
workos vault get <id> [--decrypt]
workos vault get-by-name <name> [--decrypt]
workos vault create --name <name> --org <orgId> [--value <secret>]   # omit --value to read from stdin
workos vault update <id> [--value <secret>] [--version-check]        # omit --value to read from stdin
workos vault delete <id>
workos vault describe <id>
workos vault list-versions <id>
workos vault run --secret ENV_VAR=vault-name [...] [--env <name>] [--dry-run] -- <command>

workos api-key list --org <orgId> [--limit]
workos api-key create --org <orgId> --name <name> [--permissions]
workos api-key validate <value>
workos api-key delete <id>

workos org-domain get <id>
workos org-domain create <domain> --org <orgId>
workos org-domain verify <id>
workos org-domain delete <id> [--yes]

workos install [options]

  --direct, -D            Use your own Anthropic API key (bypass llm-gateway)
  --api-key <key>         WorkOS API key (required in non-interactive mode)
  --client-id <id>        WorkOS client ID (required in non-interactive mode)
  --redirect-uri <uri>    Custom redirect URI
  --homepage-url <url>    Custom homepage URL
  --install-dir <path>    Installation directory
  --scaffold              Scaffold a new Next.js app when run in an empty directory
  --pm <manager>          Package manager for the scaffolded app: npm, pnpm, yarn, bun
  --no-validate           Skip post-installation validation
  --no-branch             Skip branch creation (use current branch)
  --commit / --no-commit  Deprecated compatibility-only no-ops
  --create-pr             Deprecated compatibility-only no-op (never publishes)
  --no-git-check          Skip git dirty working tree check
  --force-install         Force install packages even if peer dependency checks fail
  --no-tui                Use plain line-by-line output instead of the full-screen installer
  --debug                 Enable verbose logging

The installer leaves generated changes unstaged and uncommitted, preserving any previously staged work. It never stages, commits, pushes, opens a pull request, or generates commit/PR text. Review the project and commit independently when ready. The deprecated Git flags above (including boolean/negated forms) are accepted but ignored; human runs show a notice, while JSON runs keep machine streams clean. Branch creation and --no-branch are unchanged: uncommitted changes are not isolated by creating a branch. Reported changed files may include pre-existing work; inspection is scoped to --install-dir. Each of its two Git commands is limited to 5 seconds and 1 MiB of buffered output. If inspection hits either limit, it reports unknown changed files (not “no changes”); review the project manually. Partial output is never presented as a complete file list.

Full-screen installer: In an interactive terminal of at least 80×24, workos install opens a full-screen view: a plain-English walkthrough of what it's doing, a task list beside it that follows the dashboard's AuthKit checklist, and tips and WorkOS news, with every question asked inline. Below 100×30 the task list becomes a single progress line under the walkthrough. When it closes, your answers, the settings it made, any warnings or errors, and the same summary a plain run prints stay in your scrollback; the agent's step-by-step output is left to the log in ~/.workos/logs/. Pass --no-tui for plain output. Smaller terminals, piped input/output, CI and agent modes, and --json always use plain or JSON output.

Empty directories: Running workos install in an empty directory scaffolds a new Next.js app with create-next-app (App Router, TypeScript, Tailwind, src/) and then wires AuthKit into it. This only happens when the directory is empty or contains nothing but VCS/editor metadata (.git, .gitignore, LICENSE, .idea, and similar). Any project file — including a README.md or a package.json — opts out, and the installer treats the directory as an existing project. Interactive runs confirm first (default yes); non-interactive/headless runs (or --scaffold) scaffold automatically and report "scaffolded": true. The package manager is resolved from how you invoked the CLI (npm_config_user_agent) unless you pass --pm.

# Interactive (recommended)
workos install

# Greenfield: scaffold a new Next.js app + AuthKit in an empty directory
mkdir my-app && cd my-app && workos install

# JSON output (explicit; requires a prior `workos auth login`)
workos org list --json

# Pipe-friendly (auto-detects non-TTY)
workos org list | jq '.organizations[].name'

# Machine-readable command discovery
workos --help --json | jq '.commands[].name'

The CLI separates output mode from interaction mode:

• --json (or non-TTY auto-detection) controls output formatting only.
• --mode human|agent|ci (or WORKOS_MODE=...) controls interaction behavior — prompts, browser launch, host trust, destructive confirmation.

For coding agents, set both axes explicitly:

WORKOS_MODE=agent workos doctor --json --skip-ai

The CLI also auto-detects non-TTY environments (piped output, CI, coding agents) and falls back to machine-friendly defaults. No flags are required — just pipe it — but explicit mode is recommended for agents.

Upgrading? The resource commands moved to the dashboard GraphQL API and their --json shapes changed in one breaking release. See MIGRATION.md for the old-to-new field table and jq snippets.

All commands produce structured JSON when piped or with --json:

workos org list | jq .
# → { "organizations": [...], "pagination": { "before": null, "after": "..." } }

workos profile list --json
# → { "data": [{ "name": "prod", "type": "production", "active": true, ... }] }

Errors go to stderr as structured JSON:

workos org list 2>&1   # not logged in → exit code 4
# → { "error": { "code": "auth_required", "message": "Not logged in..." } }

When a coding agent drives the CLI, set agent mode explicitly so behavior is deterministic regardless of TTY:

WORKOS_MODE=agent workos doctor --json --skip-ai
WORKOS_MODE=agent workos install --api-key ... --client-id ...

In agent mode the CLI:

• Never prompts. Missing required arguments fail with structured errors instead of opening prompts.
• Treats browser launch as best-effort. Auth flows always print the manual URL and code.
• Probes host capabilities (home directory, keychain, browser launch). Host failures emit a HOST_EXECUTION_UNTRUSTED issue from workos doctor so agents can recognize sandboxed runs.
• Requires explicit confirmation flags (e.g. --yes, --force) for destructive operations.

In ci mode the CLI additionally refuses browser-based auth flows and prefers terse failures over recovery handoff text.

Mode resolution notes:

• WORKOS_MODE=agent sets agent interaction behavior and forces JSON output. (This replaces the removed WORKOS_NO_PROMPT alias.)
• WORKOS_FORCE_TTY=1 forces human output mode but does not change interaction mode.
• Non-TTY without an explicit mode still defaults output to JSON and interaction to agent.

In non-TTY, the installer streams progress as NDJSON (one JSON object per line):

workos install --api-key sk_test_xxx --client-id client_xxx 2>/dev/null
# → {"type":"detection:complete","integration":"nextjs","timestamp":"..."}
# → {"type":"agent:start","timestamp":"..."}
# → {"type":"agent:progress","message":"...","timestamp":"..."}
# → {"type":"complete","success":true,"timestamp":"..."}

WORKOS_API_URL controls where the CLI's own commands (workos user, workos api, etc.) send requests — set it to point the CLI at a locally-running API. This is distinct from workos dev, which sets API vars for your app's dev process so it talks to the in-process emulator.

Agents can introspect available commands:

workos --help --json              # Full command tree
workos profile --help --json          # Subcommand tree
workos organization --help --json # With positionals and option types

The CLI uses WorkOS Connect OAuth device flow for authentication:

# Login (opens browser for authentication)
workos auth login

# Check current auth status
workos auth status

# Logout (clears stored credentials)
workos auth logout

OAuth credentials are stored in the system keychain (with ~/.workos/credentials.json fallback). Access tokens are not persisted long-term for security - users re-authenticate when tokens expire.

1. Detects your framework and project structure
2. Resolves credentials — uses existing config, or auto-provisions an unclaimed environment if none found
3. Prepares local environment variables securely
4. Fetches latest SDK documentation from workos.com
5. Uses AI (Claude) to install the SDK and create auth routes, middleware, and UI
6. Checks the generated integration
7. Configures sandbox URLs after the agent, using one WorkOS target: the client-ID-matched dashboard application, or the API-key-only fallback. Existing settings are preserved unless an explicit override is allowed; unsupported or unverified settings are reported for manual setup.
8. Reports what was configured and what still needs attention. For React and vanilla JS, the agent creates /login, but the installer leaves the Initiate login URI unchanged: open /login while signed out, confirm it starts sign-in without a click, then set that URL in the WorkOS dashboard. Static source checks cannot verify client routing; unsupported layouts or scan limits do not by themselves fail installation. Test sign-in, sign-out, and invitation/password-reset flows in the browser before treating the integration as complete.

The CLI collects anonymous usage telemetry to help improve the product:

• Command events -- command name, duration, success/failure, termination reason, and which flags were used (for telemetry-enabled commands; install uses session events instead)
• Session events -- framework detected, step timing, token usage (installer only)
• Crash events -- sanitized error type and stack trace (no secrets, truncated to 4KB)

Environment fingerprint (OS, Node version, shell, CI detection) is included on all events. No code, credentials, or personal data is collected.

Disable with:

WORKOS_TELEMETRY=false workos <command>

Detailed logs (with redacted credentials) are saved to:

~/.workos/logs/workos-{timestamp}.log

Up to 10 session log files are retained. Use --debug flag for verbose terminal output.

See DEVELOPMENT.md for development setup.

Build:

bun run build

Run locally:

bun run dev  # Watch mode
./dist/workos --help

MIT © WorkOS