{"id":43007748,"url":"https://github.com/workos/cli","last_synced_at":"2026-04-02T13:45:16.444Z","repository":{"id":334288392,"uuid":"1133828937","full_name":"workos/cli","owner":"workos","description":"AI-powered CLI wizard that automatically integrates WorkOS AuthKit into your app","archived":false,"fork":false,"pushed_at":"2026-03-30T15:13:37.000Z","size":8519,"stargazers_count":25,"open_issues_count":3,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-30T16:30:07.735Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/workos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-13T21:50:24.000Z","updated_at":"2026-03-30T15:13:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/workos/cli","commit_stats":null,"previous_names":["workos/wizard"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/workos/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workos","download_url":"https://codeload.github.com/workos/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31257008,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T18:32:52.363Z","status":"ssl_error","status_checked_at":"2026-03-31T18:32:51.507Z","response_time":111,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-31T05:03:49.582Z","updated_at":"2026-04-02T13:45:16.431Z","avatar_url":"https://github.com/workos.png","language":"TypeScript","funding_links":[],"categories":["Auth and Identity"],"sub_categories":[],"readme":"# workos\n\nWorkOS CLI for installing AuthKit integrations and managing WorkOS resources.\n\n## Installation\n\n```bash\n# Run directly with npx (recommended)\nnpx workos\n\n# Or install globally\nnpm install -g workos\nworkos\n```\n\n## Features\n\n- **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\n- **AI-Powered:** Uses Claude to intelligently adapt to your project structure\n- **Security-First:** Masks API keys, redacts from logs, saves to .env.local\n- **Smart Detection:** Auto-detects framework, package manager, router type\n- **Live Documentation:** Fetches latest SDK docs from WorkOS and GitHub\n- **Full Integration:** Creates routes, middleware, environment vars, and UI\n- **Agent \u0026 CI Ready:** Non-TTY auto-detection, JSON output, structured errors, headless installer with NDJSON streaming\n\n## What It Creates\n\nDepending on your framework, the installer creates:\n\n- ✅ Authentication routes (callback, sign-in, sign-out)\n- ✅ Middleware for route protection\n- ✅ Environment variable configuration\n- ✅ SDK installation with correct package manager\n- ✅ UI components showing login status\n- ✅ User info display (name, email)\n\n## Credentials\n\nGet your credentials from [dashboard.workos.com](https://dashboard.workos.com):\n\n- **API Key** (sk_test_xxx or sk_live_xxx) - For server-side frameworks only\n- **Client ID** (client_xxx) - Required for all frameworks\n\n**Security:** API keys are masked during input and redacted in logs.\n\n## CLI Options\n\n```bash\nworkos [command]\n\nCommands:\n  install                Install WorkOS AuthKit into your project\n  auth                   Manage authentication (login, logout, status)\n  env                    Manage environment configurations (add, remove, switch, list, claim)\n  doctor                 Diagnose WorkOS integration issues\n  skills                 Manage WorkOS skills for coding agents (install, uninstall, list)\n\nSkills are automatically installed to detected coding agents when you run `workos install`. Use `workos skills list` to check status.\n\nResource Management:\n  organization (org)     Manage organizations\n  user                   Manage users\n  role                   Manage roles (RBAC)\n  permission             Manage permissions (RBAC)\n  membership             Manage organization memberships\n  invitation             Manage user invitations\n  session                Manage user sessions\n  connection             Manage SSO connections\n  directory              Manage directory sync\n  event                  Query events\n  audit-log              Manage audit logs\n  feature-flag           Manage feature flags\n  webhook                Manage webhooks\n  config                 Manage redirect URIs, CORS, homepage URL\n  portal                 Generate Admin Portal links\n  vault                  Manage encrypted secrets\n  api-key                Manage per-org API keys\n  org-domain             Manage organization domains\n\nWorkflows:\n  seed                   Declarative resource provisioning from YAML\n  setup-org              One-shot organization onboarding\n  onboard-user           Send invitation and assign role\n  debug-sso              Diagnose SSO connection issues\n  debug-sync             Diagnose directory sync issues\n```\n\nAll management commands support `--json` for structured output (auto-enabled in non-TTY) and `--api-key` to override the active environment's key.\n\n### Unclaimed Environments\n\nWhen you run `workos install` without credentials, the CLI automatically provisions a temporary WorkOS environment — no account needed. This lets you try AuthKit immediately.\n\n```bash\n# Install with zero setup — environment provisioned automatically\nworkos install\n\n# Check your environment\nworkos env list\n# Shows: unclaimed (unclaimed) ← active\n\n# Claim the environment to link it to your WorkOS account\nworkos env claim\n```\n\nManagement commands work on unclaimed environments with a warning reminding you to claim.\n\n### Workflows\n\nThe compound workflow commands compose multiple API calls into common operations. These are the highest-value commands for both developers and AI agents.\n\n#### seed — Declarative resource provisioning\n\nProvision permissions, roles, organizations, and config from a YAML file. Tracks created resources for clean teardown.\n\n```bash\n# Apply a seed file\nworkos seed --file workos-seed.yml\n\n# Tear down everything the seed created (reads .workos-seed-state.json)\nworkos seed --clean\n```\n\nExample `workos-seed.yml`:\n\n```yaml\npermissions:\n  - name: Read Posts\n    slug: posts:read\n  - name: Write Posts\n    slug: posts:write\n\nroles:\n  - name: Editor\n    slug: editor\n    permissions: [posts:read, posts:write]\n  - name: Viewer\n    slug: viewer\n    permissions: [posts:read]\n\norganizations:\n  - name: Acme Corp\n    domains: [acme.com]\n\nconfig:\n  redirect_uris:\n    - http://localhost:3000/callback\n  cors_origins:\n    - http://localhost:3000\n  homepage_url: http://localhost:3000\n```\n\nResources are created in dependency order (permissions → roles → organizations → config). State is tracked in `.workos-seed-state.json` so `--clean` removes exactly what was created.\n\n#### setup-org — One-shot organization onboarding\n\nCreates an organization with optional domain verification, roles, and an Admin Portal link in a single command.\n\n```bash\n# Minimal: just create the org\nworkos setup-org \"Acme Corp\"\n\n# Full: org + domain + roles + portal link\nworkos setup-org \"Acme Corp\" --domain acme.com --roles admin,viewer\n```\n\n#### onboard-user — User invitation workflow\n\nSends an invitation to a user with an optional role assignment. With `--wait`, polls until the invitation is accepted.\n\n```bash\n# Send invitation\nworkos onboard-user alice@acme.com --org org_01ABC123\n\n# Send with role and wait for acceptance\nworkos onboard-user alice@acme.com --org org_01ABC123 --role admin --wait\n```\n\n#### debug-sso — SSO connection diagnostics\n\nInspects an SSO connection's state and recent authentication events. Flags inactive connections and surfaces auth event history for debugging.\n\n```bash\nworkos debug-sso conn_01ABC123\n```\n\n#### debug-sync — Directory sync diagnostics\n\nInspects a directory's sync state, user/group counts, recent events, and detects stalled syncs.\n\n```bash\nworkos debug-sync directory_01ABC123\n```\n\n\u003c!-- UNRELEASED: Local Development (emulator) — hidden until beta testing is complete.\n     To restore, uncomment this section and re-enable the `emulate` and `dev` commands\n     in src/bin.ts and src/utils/help-json.ts.\n\n### Local Development\n\nTest your WorkOS integration locally without hitting the live API. The emulator provides a full in-memory WorkOS API replacement with all major endpoints.\n\n#### `workos dev` — One command to start everything\n\nThe fastest way to develop locally. Starts the emulator and your app together, auto-detecting your framework and injecting the right environment variables.\n\n```bash\n# Auto-detects framework (Next.js, Vite, Remix, SvelteKit, etc.) and dev command\nworkos dev\n\n# Override the dev command\nworkos dev -- npx vite --port 5173\n\n# Custom emulator port and seed data\nworkos dev --port 8080 --seed workos-emulate.config.yaml\n```\n\nYour app receives these environment variables automatically:\n\n- `WORKOS_API_BASE_URL` — points to the local emulator (e.g. `http://localhost:4100`)\n- `WORKOS_API_KEY` — `sk_test_default`\n- `WORKOS_CLIENT_ID` — `client_emulate`\n\n#### `workos emulate` — Standalone emulator\n\nRun the emulator on its own for CI, test suites, or when you want manual control.\n\n```bash\n# Start with defaults (port 4100)\nworkos emulate\n\n# CI-friendly: JSON output, custom port\nworkos emulate --port 9100 --json\n# → {\"url\":\"http://localhost:9100\",\"port\":9100,\"apiKey\":\"sk_test_default\",\"health\":\"http://localhost:9100/health\"}\n\n# Pre-load seed data\nworkos emulate --seed workos-emulate.config.yaml\n```\n\nThe emulator supports `GET /health` for readiness polling and shuts down cleanly on Ctrl+C.\n\n#### Seed configuration\n\nCreate a `workos-emulate.config.yaml` (auto-detected) or pass `--seed \u003cpath\u003e`:\n\n```yaml\nusers:\n  - email: alice@acme.com\n    first_name: Alice\n    password: test123\n    email_verified: true\n\norganizations:\n  - name: Acme Corp\n    domains:\n      - domain: acme.com\n        state: verified\n    memberships:\n      - user_id: \u003cuser_id\u003e\n        role: admin\n\nconnections:\n  - name: Acme SSO\n    organization: Acme Corp\n    connection_type: GenericSAML\n    domains: [acme.com]\n\nroles:\n  - slug: admin\n    name: Admin\n    permissions: [posts:read, posts:write]\n\npermissions:\n  - slug: posts:read\n    name: Read Posts\n  - slug: posts:write\n    name: Write Posts\n\nwebhookEndpoints:\n  - url: http://localhost:3000/webhooks\n    events: [user.created, organization.updated]\n```\n\n#### Programmatic API\n\nUse the emulator directly in test suites without the CLI:\n\n```typescript\nimport { createEmulator } from 'workos/emulate';\n\nconst emulator = await createEmulator({\n  port: 0, // random available port\n  seed: {\n    users: [{ email: 'test@example.com', password: 'secret' }],\n  },\n});\n\n// Use emulator.url as your WORKOS_API_BASE_URL\nconst res = await fetch(`${emulator.url}/user_management/users`, {\n  headers: { Authorization: 'Bearer sk_test_default' },\n});\n\n// Reset between tests (clears data, re-applies seed)\nemulator.reset();\n\n// Clean up\nawait emulator.close();\n```\n\n#### Emulated endpoints\n\nThe emulator covers the full WorkOS API surface (~84% of OpenAPI spec endpoints). Run `pnpm check:coverage \u003copenapi-spec\u003e` to see exact coverage.\n\n| Endpoint Group           | Routes                                                                                                                                                                 |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Organizations            | CRUD, external_id lookup, domain management                                                                                                                            |\n| Users                    | CRUD, email uniqueness, password management                                                                                                                            |\n| Organization memberships | CRUD, role assignment, deactivate/reactivate                                                                                                                           |\n| Organization domains     | CRUD, verification                                                                                                                                                     |\n| SSO connections          | CRUD, domain-based lookup                                                                                                                                              |\n| SSO flow                 | Authorize, token exchange, profile, JWKS, SSO logout                                                                                                                   |\n| AuthKit                  | OAuth authorize (login_hint, multi-user), authenticate (7 grant types incl. refresh_token, MFA TOTP, org selection, device code), PKCE, sealed sessions, impersonation |\n| Sessions                 | List, revoke, logout redirect, JWKS per client                                                                                                                         |\n| Email verification       | Send code, confirm                                                                                                                                                     |\n| Password reset           | Create token, confirm                                                                                                                                                  |\n| Magic auth               | Create code                                                                                                                                                            |\n| Auth factors             | TOTP enrollment, delete                                                                                                                                                |\n| MFA challenges           | Create challenge, verify code                                                                                                                                          |\n| Invitations              | CRUD, accept, revoke, resend, get by token                                                                                                                             |\n| Config                   | Redirect URIs, CORS origins, JWT template                                                                                                                              |\n| User features            | Authorized apps, connected accounts, data providers                                                                                                                    |\n| Widgets                  | Token generation                                                                                                                                                       |\n| Authorization (RBAC)     | Environment roles, org roles (priority ordering), permissions, role-permission management                                                                              |\n| Authorization (FGA)      | Resources CRUD, permission checks, role assignments                                                                                                                    |\n| Directory Sync           | List/get/delete directories, users, groups                                                                                                                             |\n| Audit Logs               | Actions, schemas, events, exports, org config/retention                                                                                                                |\n| Feature Flags            | List/get, enable/disable, targets, org/user evaluations                                                                                                                |\n| Connect                  | Applications CRUD, client secrets                                                                                                                                      |\n| Data Integrations        | OAuth authorize + token exchange                                                                                                                                       |\n| Radar                    | Attempts list/get, allow/deny lists                                                                                                                                    |\n| API Keys                 | Validate, delete, list by org                                                                                                                                          |\n| Portal                   | Generate admin portal links                                                                                                                                            |\n| Legacy MFA               | Enroll/get/delete factors, challenge/verify                                                                                                                            |\n| Webhook Endpoints        | CRUD with auto-generated secrets, secret masking                                                                                                                       |\n| Events                   | Paginated event stream with type filtering                                                                                                                             |\n| Event Bus                | Auto-emits events on entity CRUD via collection hooks, fire-and-forget webhook delivery with HMAC signatures                                                           |\n| Pipes                    | Connection CRUD, mock `getAccessToken()`                                                                                                                               |\n\nJWT tokens include `role` and `permissions` claims for org-scoped sessions. All list endpoints support cursor pagination (`before`, `after`, `limit`, `order`). Error responses match the WorkOS format (`{ message, code, errors }`).\n\nEND UNRELEASED --\u003e\n\n### Environment Management\n\n```bash\nworkos env add [name] [apiKey]   # Add environment (interactive if no args)\nworkos env remove \u003cname\u003e         # Remove an environment\nworkos env switch [name]         # Switch active environment\nworkos env list                  # List environments with active indicator\n```\n\nAPI keys are stored in the system keychain via `@napi-rs/keyring`, with a JSON file fallback at `~/.workos/config.json`.\n\n### Resource Management\n\nAll resource commands follow the same pattern: `workos \u003cresource\u003e \u003caction\u003e [args] [--options]`. API keys resolve via: `WORKOS_API_KEY` env var → `--api-key` flag → active environment's stored key.\n\n#### organization\n\n```bash\nworkos organization create \u003cname\u003e [domain:state ...]\nworkos organization update \u003corgId\u003e \u003cname\u003e [domain] [state]\nworkos organization get \u003corgId\u003e\nworkos organization list [--domain] [--limit] [--before] [--after] [--order]\nworkos organization delete \u003corgId\u003e\n```\n\n#### user\n\n```bash\nworkos user get \u003cuserId\u003e\nworkos user list [--email] [--organization] [--limit]\nworkos user update \u003cuserId\u003e [--first-name] [--last-name] [--email-verified] [--password] [--external-id]\nworkos user delete \u003cuserId\u003e\n```\n\n#### role\n\n```bash\nworkos role list [--org \u003corgId\u003e]\nworkos role get \u003cslug\u003e [--org \u003corgId\u003e]\nworkos role create --slug \u003cslug\u003e --name \u003cname\u003e [--org \u003corgId\u003e]\nworkos role update \u003cslug\u003e [--name] [--description] [--org \u003corgId\u003e]\nworkos role delete \u003cslug\u003e --org \u003corgId\u003e\nworkos role set-permissions \u003cslug\u003e --permissions \u003cslugs\u003e [--org \u003corgId\u003e]\nworkos role add-permission \u003cslug\u003e \u003cpermissionSlug\u003e [--org \u003corgId\u003e]\nworkos role remove-permission \u003cslug\u003e \u003cpermissionSlug\u003e --org \u003corgId\u003e\n```\n\n#### permission\n\n```bash\nworkos permission list [--limit]\nworkos permission get \u003cslug\u003e\nworkos permission create --slug \u003cslug\u003e --name \u003cname\u003e [--description]\nworkos permission update \u003cslug\u003e [--name] [--description]\nworkos permission delete \u003cslug\u003e\n```\n\n#### membership\n\n```bash\nworkos membership list [--org] [--user] [--limit]\nworkos membership get \u003cid\u003e\nworkos membership create --org \u003corgId\u003e --user \u003cuserId\u003e [--role]\nworkos membership update \u003cid\u003e [--role]\nworkos membership delete \u003cid\u003e\nworkos membership deactivate \u003cid\u003e\nworkos membership reactivate \u003cid\u003e\n```\n\n#### invitation\n\n```bash\nworkos invitation list [--org] [--email] [--limit]\nworkos invitation get \u003cid\u003e\nworkos invitation send --email \u003cemail\u003e [--org] [--role] [--expires-in-days]\nworkos invitation revoke \u003cid\u003e\nworkos invitation resend \u003cid\u003e\n```\n\n#### session\n\n```bash\nworkos session list \u003cuserId\u003e [--limit]\nworkos session revoke \u003csessionId\u003e\n```\n\n#### connection\n\n```bash\nworkos connection list [--org] [--type] [--limit]\nworkos connection get \u003cid\u003e\nworkos connection delete \u003cid\u003e [--force]\n```\n\n#### directory\n\n```bash\nworkos directory list [--org] [--limit]\nworkos directory get \u003cid\u003e\nworkos directory delete \u003cid\u003e [--force]\nworkos directory list-users [--directory] [--group] [--limit]\nworkos directory list-groups --directory \u003cid\u003e [--limit]\n```\n\n#### event\n\n```bash\nworkos event list --events \u003ctypes\u003e [--org] [--range-start] [--range-end] [--limit]\n```\n\n#### audit-log\n\n```bash\nworkos audit-log create-event \u003corgId\u003e --action \u003caction\u003e --actor-type \u003ctype\u003e --actor-id \u003cid\u003e [--file \u003cjson\u003e]\nworkos audit-log export --org \u003corgId\u003e --range-start \u003cdate\u003e --range-end \u003cdate\u003e [--actions] [--actor-names]\nworkos audit-log list-actions\nworkos audit-log get-schema \u003caction\u003e\nworkos audit-log create-schema \u003caction\u003e --file \u003cschema.json\u003e\nworkos audit-log get-retention \u003corgId\u003e\n```\n\n#### feature-flag\n\n```bash\nworkos feature-flag list [--limit]\nworkos feature-flag get \u003cslug\u003e\nworkos feature-flag enable \u003cslug\u003e\nworkos feature-flag disable \u003cslug\u003e\nworkos feature-flag add-target \u003cslug\u003e \u003ctargetId\u003e\nworkos feature-flag remove-target \u003cslug\u003e \u003ctargetId\u003e\n```\n\n#### webhook\n\n```bash\nworkos webhook list\nworkos webhook create --url \u003cendpoint\u003e --events \u003ctypes\u003e\nworkos webhook delete \u003cid\u003e\n```\n\n#### config\n\n```bash\nworkos config redirect add \u003curi\u003e\nworkos config cors add \u003corigin\u003e\nworkos config homepage-url set \u003curl\u003e\n```\n\n#### portal\n\n```bash\nworkos portal generate-link --intent \u003cintent\u003e --org \u003corgId\u003e [--return-url] [--success-url]\n```\n\n#### vault\n\n```bash\nworkos vault list [--limit]\nworkos vault get \u003cid\u003e\nworkos vault get-by-name \u003cname\u003e\nworkos vault create --name \u003cname\u003e --value \u003csecret\u003e [--org \u003corgId\u003e]\nworkos vault update \u003cid\u003e --value \u003csecret\u003e [--version-check]\nworkos vault delete \u003cid\u003e\nworkos vault describe \u003cid\u003e\nworkos vault list-versions \u003cid\u003e\n```\n\n#### api-key\n\n```bash\nworkos api-key list --org \u003corgId\u003e [--limit]\nworkos api-key create --org \u003corgId\u003e --name \u003cname\u003e [--permissions]\nworkos api-key validate \u003cvalue\u003e\nworkos api-key delete \u003cid\u003e\n```\n\n#### org-domain\n\n```bash\nworkos org-domain get \u003cid\u003e\nworkos org-domain create \u003cdomain\u003e --org \u003corgId\u003e\nworkos org-domain verify \u003cid\u003e\nworkos org-domain delete \u003cid\u003e\n```\n\n### Installer Options\n\n```bash\nworkos install [options]\n\n  --direct, -D            Use your own Anthropic API key (bypass llm-gateway)\n  --integration \u003cname\u003e    Framework: nextjs, react, react-router, tanstack-start, vanilla-js, sveltekit, node, python, ruby, go, dotnet, kotlin, elixir, php-laravel, php\n  --api-key \u003ckey\u003e         WorkOS API key (required in non-interactive mode)\n  --client-id \u003cid\u003e        WorkOS client ID (required in non-interactive mode)\n  --redirect-uri \u003curi\u003e    Custom redirect URI\n  --homepage-url \u003curl\u003e    Custom homepage URL\n  --install-dir \u003cpath\u003e    Installation directory\n  --no-validate           Skip post-installation validation\n  --no-branch             Skip branch creation (use current branch)\n  --no-commit             Skip auto-commit after installation\n  --create-pr             Auto-create pull request after installation\n  --no-git-check          Skip git dirty working tree check\n  --force-install         Force install packages even if peer dependency checks fail\n  --debug                 Enable verbose logging\n```\n\n## Examples\n\n```bash\n# Interactive (recommended)\nnpx workos\n\n# Specify framework\nnpx workos install --integration react-router\n\n# With visual dashboard (experimental)\nnpx workos dashboard\n\n# JSON output (explicit)\nworkos org list --json --api-key sk_test_xxx\n\n# Pipe-friendly (auto-detects non-TTY)\nworkos org list --api-key sk_test_xxx | jq '.data[].name'\n\n# Machine-readable command discovery\nworkos --help --json | jq '.commands[].name'\n```\n\n## Scripting \u0026 Automation\n\nThe CLI auto-detects non-TTY environments (piped output, CI, coding agents) and switches to machine-friendly behavior. No flags required — just pipe it.\n\n### JSON Output\n\nAll commands produce structured JSON when piped or with `--json`:\n\n```bash\nworkos org list --api-key sk_test_xxx | jq .\n# → { \"data\": [...], \"list_metadata\": { \"before\": null, \"after\": \"...\" } }\n\nworkos env list --json\n# → { \"data\": [{ \"name\": \"prod\", \"type\": \"production\", \"active\": true, ... }] }\n```\n\nErrors go to stderr as structured JSON:\n\n```bash\nworkos org list 2\u003e\u00261\n# → { \"error\": { \"code\": \"no_api_key\", \"message\": \"No API key configured...\" } }\n```\n\n### Headless Installer\n\nIn non-TTY, the installer streams progress as NDJSON (one JSON object per line):\n\n```bash\nworkos install --api-key sk_test_xxx --client-id client_xxx --no-commit 2\u003e/dev/null\n# → {\"type\":\"detection:complete\",\"integration\":\"nextjs\",\"timestamp\":\"...\"}\n# → {\"type\":\"agent:start\",\"timestamp\":\"...\"}\n# → {\"type\":\"agent:progress\",\"message\":\"...\",\"timestamp\":\"...\"}\n# → {\"type\":\"complete\",\"success\":true,\"timestamp\":\"...\"}\n```\n\n### Exit Codes\n\n| Code | Meaning                 |\n| ---- | ----------------------- |\n| 0    | Success                 |\n| 1    | General error           |\n| 2    | Cancelled               |\n| 4    | Authentication required |\n\n### Environment Variables\n\n| Variable                 | Effect                                                    |\n| ------------------------ | --------------------------------------------------------- |\n| `WORKOS_API_KEY`         | API key for management commands (bypasses stored config)  |\n| `WORKOS_API_BASE_URL`    | Override API base URL (set automatically by `workos dev`) |\n| `WORKOS_NO_PROMPT=1`     | Force non-interactive mode + JSON output                  |\n| `WORKOS_FORCE_TTY=1`     | Force interactive mode even when piped                    |\n| `WORKOS_TELEMETRY=false` | Disable telemetry                                         |\n\n### Command Discovery\n\nAgents can introspect available commands:\n\n```bash\nworkos --help --json              # Full command tree\nworkos env --help --json          # Subcommand tree\nworkos organization --help --json # With positionals and option types\n```\n\n## Authentication\n\nThe CLI uses WorkOS Connect OAuth device flow for authentication:\n\n```bash\n# Login (opens browser for authentication)\nworkos auth login\n\n# Check current auth status\nworkos auth status\n\n# Logout (clears stored credentials)\nworkos auth logout\n```\n\nOAuth 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.\n\n## How It Works\n\n1. **Detects** your framework and project structure\n2. **Resolves credentials** — uses existing config, or auto-provisions an unclaimed environment if none found\n3. **Auto-configures** WorkOS dashboard (redirect URI, CORS, homepage URL)\n4. **Fetches** latest SDK documentation from workos.com\n5. **Uses AI** (Claude) to generate integration code\n6. **Installs** SDK with detected package manager\n7. **Creates** auth routes, middleware, and UI\n8. **Configures** environment variables securely\n\n## Telemetry\n\nThe installer collects anonymous usage telemetry to help improve the product:\n\n- Session outcome (success/error/cancelled)\n- Framework detected\n- Duration and step timing\n- Token usage (for capacity planning)\n\nNo code, credentials, or personal data is collected. Disable with:\n\n```bash\nWORKOS_TELEMETRY=false npx workos\n```\n\n## Logs\n\nDetailed logs (with redacted credentials) are saved to:\n\n```\n~/.workos/logs/workos-{timestamp}.log\n```\n\nUp to 10 session log files are retained. Use `--debug` flag for verbose terminal output.\n\n## Development\n\nSee [DEVELOPMENT.md](./DEVELOPMENT.md) for development setup.\n\nBuild:\n\n```bash\npnpm build\n```\n\nRun locally:\n\n```bash\npnpm dev  # Watch mode\n./dist/bin.js --help\n```\n\n## License\n\nMIT © WorkOS\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkos%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fcli/lists"}