gem-hunter
Language: TypeScript
AI-powered CLI wizard that automatically integrates WorkOS AuthKit into your app
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 installcreate-next-app) before wiring AuthKitDepending on your framework, the installer creates:
Get your credentials from dashboard.workos.com:
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
--jsonshapes changed in one breaking release. See MIGRATION.md for the old-to-new field table andjqsnippets.
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:
HOST_EXECUTION_UNTRUSTED issue from workos doctor so agents can recognize sandboxed runs.--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.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":"..."}
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Canceled |
| 4 | Authentication required |
| Variable | Effect |
|---|---|
WORKOS_API_KEY |
API key for workos api, the still-REST commands (connection, directory, audit-log, api-key, vault), and workflow/debug commands. Resource commands use the workos auth login session instead |
WORKOS_API_URL |
Override the API base URL for all CLI commands (e.g. a local API) |
WORKOS_API_BASE_URL |
Accepted alias for WORKOS_API_URL (what workos dev sets) |
WORKOS_MODE |
Interaction mode: human, agent, or ci |
WORKOS_FORCE_TTY=1 |
Force human (non-JSON) output mode even when piped |
WORKOS_TELEMETRY=false |
Disable telemetry |
WORKOS_API_URLcontrols 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 fromworkos 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.
/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:
install uses session events instead)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 --helpMIT © WorkOS