Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
20d2ef3
feat: run organization and org-domain commands with an API key
nicknisi Nov 11, 2026
62d618f
feat: run user and session commands with an API key
nicknisi Nov 11, 2026
f7f3217
feat: run membership and invitation commands with an API key
nicknisi Nov 11, 2026
6d5b201
feat: run role and permission commands with an API key
nicknisi Nov 11, 2026
f191016
feat: run webhook, event, portal and feature-flag commands with an AP…
nicknisi Nov 11, 2026
8b13b0c
feat: run config and authkit URI/CORS commands with an API key
nicknisi Nov 11, 2026
9ce531c
test: cover resource commands with an API key, including session parity
nicknisi Nov 11, 2026
a02ff2a
test: compare session and API-key output live in parity-smoke --api-key
nicknisi Nov 11, 2026
da5d058
fix: type-check the API-key path and drop unused exports
nicknisi Nov 11, 2026
713b9fa
docs: say resource commands accept an API key
nicknisi Nov 11, 2026
c25c9e0
riker: uncommitted changes from job 320
nicknisi Nov 11, 2026
5311a06
fix: make API-key writes fail safe and map states like the dashboard
nicknisi Nov 11, 2026
98e8410
test: tighten the session-vs-key parity gate offline and live
nicknisi Nov 11, 2026
3116b09
riker: uncommitted changes from job 320
nicknisi Nov 11, 2026
6798581
riker: uncommitted changes from job 320
nicknisi Nov 11, 2026
94ec2e8
test: assert each flag command makes exactly its own REST write
nicknisi Nov 11, 2026
79bd0eb
test: make parity-smoke --api-key fail when it compared no entity
nicknisi Nov 11, 2026
21c19a4
riker: uncommitted changes from job 320
nicknisi Nov 11, 2026
9a38951
fix: read every page and every membership status on the API-key path
nicknisi Nov 11, 2026
c81eba7
riker: uncommitted changes from job 320
nicknisi Nov 11, 2026
422842c
fix: keep `after` as the next page on every API-key list
nicknisi Nov 11, 2026
3ce1b1a
riker: uncommitted changes from job 320
nicknisi Nov 11, 2026
4a5d8a4
fix: keep the DNS challenge when domains are added or verified with a…
nicknisi Nov 11, 2026
d93f791
fix: fail instead of truncating API-key lists past 5,000 records
nicknisi Nov 11, 2026
952a886
test: check --api-key precedence through the real command line
nicknisi Nov 11, 2026
e5c09dc
riker: uncommitted changes from job 320
nicknisi Nov 11, 2026
999ca56
test: stop the live parity gate from skipping cursor-named fields
nicknisi Nov 11, 2026
c309c6f
fix: report membership roles the way the dashboard does on the API-ke…
nicknisi Nov 11, 2026
38c2076
test: keep each parity-smoke side on the plane it claims to test
nicknisi Nov 11, 2026
fab3c63
riker: uncommitted changes from job 320
nicknisi Nov 11, 2026
ef1431a
test: never let a hung CLI child outlive the --api-key integration test
nicknisi Nov 16, 2026
6abbf18
chore: drop scratch PR body from the branch
nicknisi Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ WorkOS CLI for installing AuthKit integrations and managing WorkOS resources (or
## Non-TTY Behavior

- **Output**: Auto-switches to JSON when piped or `--json` flag. `WORKOS_FORCE_TTY=1` overrides.
- **Auth**: Exits code 4 instead of opening browser. Resource commands (organization, user, role, permission, membership, invitation, session, event, feature-flag, org-domain, portal, webhook, config) use the dashboard session from a prior `workos auth login`; expired access tokens refresh silently while the stored refresh token is valid, so only a truly dead session exits 4. `WORKOS_API_KEY` applies only to `workos api` and the still-REST commands (`connection`, `directory`, `audit-log`, `api-key`, `vault`, plus the workflow/debug commands `seed`, `setup-org`, `onboard-user`, `verify-login`, `debug-sso`, `debug-sync`, `migrations`).
- **Auth**: Exits code 4 instead of opening browser. Resource commands (organization, user, role, permission, membership, invitation, session, event, feature-flag, org-domain, portal, webhook, config, authkit, branding) use the dashboard session from a prior `workos auth login`; expired access tokens refresh silently while the stored refresh token is valid, so only a truly dead session exits 4. They switch to an API key on the WorkOS REST API when one applies (first match: `--api-key`, `WORKOS_API_KEY`, the active profile's key if it is unclaimed); `src/lib/resource-auth.ts` decides, and `src/lib/api-key-operations/` maps each operation to REST with the same `--json` shape. With a key, `--environment-id` is refused, and AuthKit logout URIs and branding fail with `api_key_unsupported`. The account commands (`team`, `project`, `environment`, `whoami`) are session-only. `WORKOS_API_KEY` also applies to `workos api` and the still-REST commands (`connection`, `directory`, `audit-log`, `api-key`, `vault`, plus the workflow/debug commands `seed`, `setup-org`, `onboard-user`, `verify-login`, `debug-sso`, `debug-sync`, `migrations`).
- **Errors**: Structured JSON to stderr: `{ "error": { "code": "...", "message": "..." } }`
- **Exit codes**: 0=success, 1=error, 2=canceled, 4=auth required (follows `gh` CLI convention)
- **Headless flags**: `--no-branch`, `--no-git-check`. CI mode (`WORKOS_MODE=ci`) auto-continues past a dirty tree without `--no-git-check`; agent mode requires the flag.
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ Workflows:
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](#resource-management)).
All management commands support `--json` for structured output (auto-enabled in non-TTY). They also accept `--api-key`: the still-REST commands (`connection`, `directory`, `audit-log`, `api-key`, `vault`, `workos api`, and the workflow/debug commands) use it to override the active environment's key, and the other resource commands use it instead of your `workos auth login` session (see [Resource Management](#resource-management)).

### Unclaimed Environments

Expand Down Expand Up @@ -309,6 +309,8 @@ All resource commands follow the same pattern: `workos <resource> <action> [args

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.

They can also run with an API key instead, against the WorkOS API. The first match wins: the `--api-key` flag, then `WORKOS_API_KEY`, then the active profile's key when that profile is an unclaimed environment (from `workos env provision` or the installer). Otherwise the dashboard session is used, so a signed-in user is unaffected unless they pass a key. With a key, the key decides the environment, so `--environment-id` is refused. AuthKit logout URIs (`authkit logout-uris`) and branding (`branding`) have no API equivalent and fail with `api_key_unsupported`. The account commands (`team`, `project`, `environment`, `whoami`) always need the dashboard session.

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.

#### organization
Expand Down Expand Up @@ -685,7 +687,7 @@ workos install --api-key sk_test_xxx --client-id client_xxx 2>/dev/null

| 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_KEY` | API key for `workos api`, the still-REST and workflow/debug commands, and the resource commands (instead of the `workos auth login` session; `team`/`project`/`environment`/`whoami` require it) |
| `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` |
Expand Down
Loading
Loading