← Files WorkOSARCHIVED FILE
references/workos-management.md
18 KB · Oct 4, 2026 · 12:06 UTC
# WorkOS Management Commands
Use these commands to manage WorkOS resources directly from the terminal. The CLI must be authenticated via `workos auth login` or `WORKOS_API_KEY` env var.
All commands support `--json` for structured output. Use `--json` when you need to parse output (e.g., extract an ID).
## Checking what the CLI can do (READ THIS FIRST)
**If a user asks whether the CLI supports operation X, or if you're about to suggest a `workos ...` command, verify it first.** The authoritative, machine-readable command tree is:
```bash
workos --help --json
```
This emits a complete JSON tree of every registered command, subcommand, and flag. If a command or subcommand is not in that output, **it does not exist** — do not invent it, do not suggest it, do not assume "it must be there." Common agent failure mode: seeing that `workos <resource>` supports `list/get/delete` and assuming `create` / `update` also exist when they don't.
**Rule**: Before suggesting any `workos` command not listed in the Quick Reference table below, either (a) run `workos --help --json` and confirm the command exists, or (b) tell the user "this doesn't appear to be in the CLI — verify with `workos --help --json`." Never guess.
**The tables below are a snapshot and may lag the published CLI.** The live `--help --json` output is the source of truth.
## Detecting and recommending CLI upgrades
If `workos --help --json` is missing a command you expected, or the user reports `unknown command: <something>` for a command that exists in the latest release, **the user is likely on an outdated CLI** rather than encountering a bug. Before suggesting a workaround:
1. Ask the user to run `workos --version`.
2. Compare against the latest published version with `npm view workos version` (do NOT guess the latest version from memory — it moves frequently).
3. If the user is behind, send them to `references/workos-cli-upgrade.md` for the upgrade command for their package manager (npm/pnpm) and the no-install `npx workos@latest` fallback.
## Quick Reference
| Task | Command |
| ---------------------- | ---------------------------------------------------------------------------- |
| List organizations | `workos organization list` |
| Create organization | `workos organization create "Acme Corp" acme.com:verified` |
| List users | `workos user list --email=alice@acme.com` |
| Create permission | `workos permission create --slug=read-users --name="Read Users"` |
| Create role | `workos role create --slug=admin --name=Admin` |
| Assign perms to role | `workos role set-permissions admin --permissions=read-users,write-users` |
| Create org-scoped role | `workos role create --slug=admin --name=Admin --org=org_xxx` |
| Add user to org | `workos membership create --org=org_xxx --user=user_xxx` |
| Send invitation | `workos invitation send --email=alice@acme.com --org=org_xxx` |
| Revoke session | `workos session revoke <sessionId>` |
| Add redirect URI | `workos config redirect add http://localhost:3000/callback` |
| Add CORS origin | `workos config cors add http://localhost:3000` |
| Set homepage URL | `workos config homepage-url set http://localhost:3000` |
| Create webhook | `workos webhook create --url=https://example.com/hook --events=user.created` |
| List SSO connections | `workos connection list --org=org_xxx` |
| List directories | `workos directory list` |
| Toggle feature flag | `workos feature-flag enable my-flag` |
| Store a secret | `workos vault create --name=api-secret --value=sk_xxx --org=org_xxx` |
| Generate portal link | `workos portal generate-link --intent=sso --org=org_xxx` |
| Seed environment | `workos seed --file=workos-seed.yml` |
| Debug SSO | `workos debug-sso conn_xxx` |
| Debug directory sync | `workos debug-sync directory_xxx` |
| Set up an org | `workos setup-org "Acme Corp" --domain=acme.com --roles=admin,viewer` |
| Onboard a user | `workos onboard-user alice@acme.com --org=org_xxx --role=admin` |
## Workflows
### Setting up RBAC
When you see permission checks in the codebase (e.g., `hasPermission('read-users')`), create the matching WorkOS resources:
```bash
workos permission create --slug=read-users --name="Read Users"
workos permission create --slug=write-users --name="Write Users"
workos role create --slug=admin --name=Admin
workos role set-permissions admin --permissions=read-users,write-users
workos role create --slug=viewer --name=Viewer
workos role set-permissions viewer --permissions=read-users
```
For organization-scoped roles, add `--org=org_xxx` to role commands.
### Organization Onboarding
One-shot setup with the compound command:
```bash
workos setup-org "Acme Corp" --domain=acme.com --roles=admin,viewer
```
Or step by step:
```bash
ORG_ID=$(workos organization create "Acme Corp" --json | jq -r '.data.id')
workos org-domain create acme.com --org=$ORG_ID
workos role create --slug=admin --name=Admin --org=$ORG_ID
workos portal generate-link --intent=sso --org=$ORG_ID
```
### User Onboarding
```bash
workos onboard-user alice@acme.com --org=org_xxx --role=admin
```
Or step by step:
```bash
workos invitation send --email=alice@acme.com --org=org_xxx --role=admin
workos membership create --org=org_xxx --user=user_xxx --role=admin
```
### Local Development Setup
Configure WorkOS for local development:
```bash
workos config redirect add http://localhost:3000/callback
workos config cors add http://localhost:3000
workos config homepage-url set http://localhost:3000
```
### Environment Seeding
Create a `workos-seed.yml` file in your repo:
```yaml
permissions:
- name: 'Read Users'
slug: 'read-users'
- name: 'Write Users'
slug: 'write-users'
roles:
- name: 'Admin'
slug: 'admin'
permissions: ['read-users', 'write-users']
- name: 'Viewer'
slug: 'viewer'
permissions: ['read-users']
organizations:
- name: 'Test Org'
domains: ['test.com']
config:
redirect_uris: ['http://localhost:3000/callback']
cors_origins: ['http://localhost:3000']
homepage_url: 'http://localhost:3000'
```
Then run:
```bash
workos seed --file=workos-seed.yml # Create resources
workos seed --clean # Tear down seeded resources
```
### Debugging SSO
```bash
workos debug-sso conn_xxx
```
Shows: connection type/state, organization binding, recent auth events, and common issues (inactive connection, org mismatch).
### Debugging Directory Sync
```bash
workos debug-sync directory_xxx
```
Shows: directory type/state, user/group counts, recent sync events, and stall detection.
### Webhook Management
```bash
workos webhook list
workos webhook create --url=https://example.com/hook --events=user.created,dsync.user.created
workos webhook delete we_xxx
```
### Audit Logs
```bash
workos audit-log create-event --org=org_xxx --action=user.login --actor-type=user --actor-id=user_xxx
workos audit-log list-actions
workos audit-log get-schema user.login
workos audit-log export --org=org_xxx --range-start=2024-01-01 --range-end=2024-02-01
workos audit-log get-retention --org=org_xxx
```
## Using --json for Structured Output
All commands support `--json` for machine-readable output. Use this when you need to extract values:
```bash
# Get an organization ID
workos organization list --json | jq '.data[0].id'
# Get a connection's state
workos connection get conn_xxx --json | jq '.state'
# List all role slugs
workos role list --json | jq '.data[].slug'
# Chain commands: create org then add domain
ORG_ID=$(workos organization create "Acme" --json | jq -r '.data.id')
workos org-domain create acme.com --org=$ORG_ID
```
JSON output format:
- **List commands**: `{ "data": [...], "listMetadata": { "before": null, "after": "cursor" } }`
- **Get commands**: Raw object (no wrapper)
- **Create/Update/Delete**: `{ "status": "ok", "message": "...", "data": {...} }`
- **Errors**: `{ "error": { "code": "...", "message": "..." } }` on stderr
## Command Reference
### Resource Commands
| Command | Subcommands |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `workos organization` | `list`, `get`, `create`, `update`, `delete` |
| `workos user` | `list`, `get`, `update`, `delete` |
| `workos role` | `list`, `get`, `create`, `update`, `delete`, `set-permissions`, `add-permission`, `remove-permission` |
| `workos permission` | `list`, `get`, `create`, `update`, `delete` |
| `workos membership` | `list`, `get`, `create`, `update`, `delete`, `deactivate`, `reactivate` |
| `workos invitation` | `list`, `get`, `send`, `revoke`, `resend` |
| `workos session` | `list`, `revoke` |
| `workos connection` | `list`, `get`, `delete` |
| `workos directory` | `list`, `get`, `delete`, `list-users`, `list-groups` |
| `workos event` | `list` (requires `--events` flag) |
| `workos audit-log` | `create-event`, `export`, `list-actions`, `get-schema`, `create-schema`, `get-retention` |
| `workos feature-flag` | `list`, `get`, `enable`, `disable`, `add-target`, `remove-target` |
| `workos webhook` | `list`, `create`, `delete` |
| `workos config` | `redirect add`, `cors add`, `homepage-url set` |
| `workos portal` | `generate-link` |
| `workos vault` | `list`, `get`, `get-by-name`, `create`, `update`, `delete`, `describe`, `list-versions` |
| `workos api-key` | `list`, `create`, `validate`, `delete` |
| `workos org-domain` | `get`, `create`, `verify`, `delete` |
### Workflow Commands
| Command | Purpose |
| ----------------------------- | ------------------------------------------- |
| `workos seed --file=<yaml>` | Declarative resource provisioning from YAML |
| `workos seed --clean` | Tear down seeded resources |
| `workos setup-org <name>` | One-shot org onboarding |
| `workos onboard-user <email>` | Send invitation + optional wait |
| `workos debug-sso <connId>` | SSO connection diagnostics |
| `workos debug-sync <dirId>` | Directory sync diagnostics |
### Common Flags
| Flag | Purpose | Scope |
| ------------------------------------------- | ------------------------ | --------------------------------------------------- |
| `--json` | Structured JSON output | All commands |
| `--api-key` | Override API key | Resource commands |
| `--org` | Organization scope | role, membership, invitation, api-key, feature-flag |
| `--force` | Skip confirmation prompt | connection delete, directory delete |
| `--limit`, `--before`, `--after`, `--order` | Pagination | All list commands |
## Not in the CLI (use Dashboard, Admin Portal, API, or a different workflow)
These operations are commonly asked for but are **not** supported in the WorkOS CLI today. Do not invent commands for them. For each, the right answer is listed.
### Dashboard / Admin Portal only
| Operation | Where it lives | Docs |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Create an SSO connection | Admin Portal (generate via `workos portal generate-link --intent=sso --org=<org_id>`) | https://workos.com/docs/sso/guide |
| Create a Directory Sync connection | Admin Portal (generate via `workos portal generate-link --intent=dsync --org=<org_id>`) | https://workos.com/docs/directory-sync/quick-start |
| Map IdP (Entra/AD/Okta/Google Workspace) groups to WorkOS roles | Admin Portal during directory setup, or directory page in Dashboard | https://workos.com/docs/directory-sync/identity-provider-role-assignment |
| Map SSO groups to WorkOS roles | Admin Portal during SSO setup, or connection page in Dashboard | https://workos.com/docs/rbac/idp-role-assignment |
| Enable/disable Admin Portal role-assignment step | Authorization page in the WorkOS Dashboard | https://workos.com/docs/directory-sync/identity-provider-role-assignment |
| Enable/disable authentication methods | Authentication settings in the WorkOS Dashboard | https://workos.com/docs/authkit |
| Configure session lifetime | Authentication settings in the WorkOS Dashboard | https://workos.com/docs/user-management/sessions |
| Set up social login providers (Google, GitHub, etc.) | Authentication settings in the WorkOS Dashboard | https://workos.com/docs/user-management/social-login |
| Create feature flags | Feature Flags page in the WorkOS Dashboard (toggle/target ops work via CLI) | https://workos.com/docs/feature-flags |
| Configure branding (logos, colors) | Branding settings in the WorkOS Dashboard | https://workos.com/docs/admin-portal/branding |
| Set up email templates | Email settings in the WorkOS Dashboard | https://workos.com/docs/emails |
| Manage billing / plan | Settings in the WorkOS Dashboard | — |
### API-only (not in CLI, but can be scripted via SDK / REST)
| Operation | Where it lives | Notes |
| -------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Assign a role to an individual user | `updateOrganizationMembership` via SDK/REST | Warning: IdP mapping silently overrides this on next sync/login when mapping exists. See `workos-rbac.md`. |
| Webhook signature verification | SDK (`workos.webhooks.verifyEvent`) | CLI can create/list/delete webhooks but does not verify events |
| Session introspection / JWT validation | SDK | CLI has `workos session list/revoke` only |
**Rule of thumb**: if a user asks "is there a CLI command for X" and X is not in the Quick Reference table above and is not produced by `workos --help --json`, the answer is **no**. Do not speculate. Point the user at the right surface per this table.
### Do not invent click-paths in the Dashboard
The paths in the "Where it lives" column above are intentionally described in conceptual terms ("Authentication settings", "directory page") rather than as literal click-paths like "Dashboard > Organizations > X > Y". The docs don't commit to exact menu paths, and the Dashboard UI is re-organized periodically. Link the user to the docs URL and let them navigate. If you see yourself writing `Dashboard > A > B > C` or `dashboard.workos.com/some/path`, stop and link to docs instead.
SHA-256: 425f02746e02fe4cc4e4bafde918cff2120763cca8a014a67218d0dcf7fc9cc8