From 4d5e62c9bb79b75960645eb9c5b0d0e8396f73f0 Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Sun, 10 May 2026 13:19:58 -0500 Subject: [PATCH 1/4] feat(workos): add CLI agent-mode guidance to skill Coding agents now have explicit instructions for invoking the WorkOS CLI: - Recommend `WORKOS_MODE=agent workos doctor --json --skip-ai` as the setup/debugging preflight. - Document the two-axis model: `--json` is output formatting only; `WORKOS_MODE=agent` controls prompts, browser fallback, and host trust. - Treat `HOST_EXECUTION_UNTRUSTED` from doctor as a hard sandbox trust boundary that requires re-running on the host shell before trusting auth/config/API failures. - Note legacy compatibility for `WORKOS_NO_PROMPT` and `WORKOS_FORCE_TTY`. - Update workos-widgets install prompts to use `WORKOS_MODE=agent` when asking the user to run `npx workos@latest install`. The CLI surface (mode resolver, doctor visibility, recovery hints) is landing in the workos/cli repo (https://github.com/workos/cli/pull/143); this skill update teaches agents to use it. --- plugins/workos/skills/workos-widgets/SKILL.md | 4 +- plugins/workos/skills/workos/SKILL.md | 69 +++++++++++++------ 2 files changed, 50 insertions(+), 23 deletions(-) diff --git a/plugins/workos/skills/workos-widgets/SKILL.md b/plugins/workos/skills/workos-widgets/SKILL.md index e260c3d..ab594a3 100644 --- a/plugins/workos/skills/workos-widgets/SKILL.md +++ b/plugins/workos/skills/workos-widgets/SKILL.md @@ -16,7 +16,7 @@ description: Use when the user is implementing, embedding, or debugging a WorkOS 3. Detect stack, data-layer style, styling, component system, and package manager using [references/detection.md](references/detection.md). 4. Check for AuthKit/WorkOS presence: - if detected, continue; - - if not detected, ask the user to run `npx workos@latest install`, wait for confirmation, then continue. + - if not detected, ask the user to run `WORKOS_MODE=agent npx workos@latest install` (agent mode keeps the installer non-interactive and surfaces structured errors with recovery hints). Wait for confirmation, then continue. 5. If detection is ambiguous or conflicting, ask one focused question, then continue. 6. Load only the relevant reference files for the detected stack and widget. 7. Implement integration based on stack shape: @@ -99,7 +99,7 @@ Then load exactly one widget reference: - Implement a consistent authorization layer for widget requests, including elevated-token handling for sensitive endpoints when required. - If the app already uses React Query or SWR, use them as orchestration/cache layers around those direct calls. - For React/TypeScript widget code quality expectations, follow [references/react-ts-standards.md](references/react-ts-standards.md). -- If AuthKit/WorkOS is missing, prompt the user to run `npx workos@latest install` before continuing. +- If AuthKit/WorkOS is missing, prompt the user to run `WORKOS_MODE=agent npx workos@latest install` before continuing. `WORKOS_MODE=agent` keeps the installer deterministic and machine-readable in agent sessions; `--json` may be added when you need to parse output. - Install additional dependencies only when strictly necessary, using the detected package manager/tooling. - Keep server-state handling aligned with the selected data-layer approach. - Use local state/reducers for UI interaction state as needed. diff --git a/plugins/workos/skills/workos/SKILL.md b/plugins/workos/skills/workos/SKILL.md index 4fca2d5..3fe5c16 100644 --- a/plugins/workos/skills/workos/SKILL.md +++ b/plugins/workos/skills/workos/SKILL.md @@ -19,11 +19,38 @@ description: Use when the user asks for a WorkOS docs URL, term, or dashboard fi These apply regardless of which routing rule fires. They exist because the most common failure mode of past WorkOS agent interactions has been plausibly-shaped fabrication of CLI commands and Dashboard paths. -- **Never invent `workos` CLI commands.** If the user asks about CLI support or you're about to suggest a command, verify the command tree first. The authoritative source is `workos --help --json` — it emits the complete registered command tree. Do not assume a `create` subcommand exists because `list`/`get`/`delete` do. See `references/workos-management.md`. +- **Never invent `workos` CLI commands.** If the user asks about CLI support or you're about to suggest a command, verify the command tree first. The authoritative source is `WORKOS_MODE=agent workos --help --json` — it emits the complete registered command tree. Do not assume a `create` subcommand exists because `list`/`get`/`delete` do. See `references/workos-management.md`. +- **Run the `workos` CLI in agent mode.** When invoking the CLI from a coding-agent session, prefix commands with `WORKOS_MODE=agent` (e.g. `WORKOS_MODE=agent workos doctor --json --skip-ai`). Agent mode controls prompts, browser fallback, and host trust; `--json` controls output formatting only. See the **WorkOS CLI in Coding-Agent Sessions** section below. - **Never invent Dashboard click-paths.** Phrases like "Dashboard > Organizations > X > Roles > Map Groups" or `dashboard.workos.com/some/specific/path` should not appear unless you have verified them against a docs page you just fetched. The Dashboard UI reorganizes; docs pages are stable. Cite the docs URL and describe the destination conceptually ("the Authorization page", "the directory's settings") instead of committing to a click-path. - **When the user wants to do something not supported by the CLI, say so plainly.** Users are better served by "this isn't in the CLI; here's the docs URL for how to do it" than by a fabricated command that fails. See the "Not in the CLI" section of `references/workos-management.md`. - **Prefer docs URLs over prose when writing recipes.** If a reference file tells you to cite a specific docs URL, cite it literally; don't paraphrase the URL's slug. +## WorkOS CLI in Coding-Agent Sessions + +When using the `workos` CLI from a coding agent, treat output mode and interaction mode as separate axes and set both explicitly. The CLI's auto-detection works, but explicit flags are more reliable across sandboxes. + +**Recommended preflight for any setup or debugging task:** + +```bash +WORKOS_MODE=agent workos doctor --json --skip-ai +``` + +This returns a structured JSON report including an `interactionMode` field (`{ mode, source }`) and a `hostExecution` block. Read the JSON before suggesting fixes. + +**Rules:** + +- Use `--json` when parsing command output. It controls **formatting only** — it does not change CLI behavior. +- Use `WORKOS_MODE=agent` even when relaying human-readable messages. It controls **prompts, browser launch, and host trust**. +- Treat the doctor `HOST_EXECUTION_UNTRUSTED` issue as a hard trust boundary. If the doctor report contains this issue (or `hostExecution.ok` is `false`), **the current shell may be sandboxed**. Auth, config, keychain, and API failures from this shell are not authoritative. Ask the user to re-run host-sensitive commands (`workos auth login`, `workos doctor`, `workos env add`) on their host shell before drawing conclusions. +- Do not assume browser-based auth (`workos auth login`) works in a sandbox. If auth is required, surface the manual URL/code fallback that the CLI prints, or ask the user to run `workos auth login` on their host shell. +- For destructive CLI commands in agent mode, pass the explicit confirmation flag (`--yes` for `workos api`, `--force` for `workos connection delete`, `workos directory delete`, etc.). Agent mode never prompts. +- Structured CLI errors include an optional `error.recovery.hints[]` array with the next deterministic command to run. Prefer those hints over guessing. + +**Legacy compatibility you may encounter:** + +- `WORKOS_NO_PROMPT=1` is a legacy alias for agent interaction behavior plus JSON output. Prefer `WORKOS_MODE=agent` in new instructions. +- `WORKOS_FORCE_TTY=1` only affects output formatting; it does not change interaction mode. + ## Topic → Reference Map > Terminology lookups — "what is X", "docs URL for X" — are handled by **Rule 0** below, not this topic map. They route to `references/workos-terms.md`. @@ -57,23 +84,23 @@ These apply regardless of which routing rule fires. They exist because the most ### Features (Read `references/{name}.md`) -| User wants to... | Read file | -| ------------------------------- | ------------------------------------- | -| Configure Single Sign-On | `references/workos-sso.md` | -| Set up Directory Sync | `references/workos-directory-sync.md` | -| Implement RBAC / roles | `references/workos-rbac.md` | -| Encrypt data with Vault | `references/workos-vault.md` | -| Handle WorkOS Events / webhooks | `references/workos-events.md` | -| Set up Audit Logs | `references/workos-audit-logs.md` | -| Enable Admin Portal | `references/workos-admin-portal.md` | -| Add Multi-Factor Auth | `references/workos-mfa.md` | -| Configure email delivery | `references/workos-email.md` | -| Set up Custom Domains | `references/workos-custom-domains.md` | -| Set up IdP integration | `references/workos-integrations.md` | -| Implement FGA / fine-grained authz | `references/workos-fga.md` | -| Set up Pipes / Connected Apps | `references/workos-pipes.md` | -| Configure Feature Flags | `references/workos-feature-flags.md` | -| Set up Radar / fraud detection | `references/workos-radar.md` | +| User wants to... | Read file | +| ---------------------------------- | ------------------------------------- | +| Configure Single Sign-On | `references/workos-sso.md` | +| Set up Directory Sync | `references/workos-directory-sync.md` | +| Implement RBAC / roles | `references/workos-rbac.md` | +| Encrypt data with Vault | `references/workos-vault.md` | +| Handle WorkOS Events / webhooks | `references/workos-events.md` | +| Set up Audit Logs | `references/workos-audit-logs.md` | +| Enable Admin Portal | `references/workos-admin-portal.md` | +| Add Multi-Factor Auth | `references/workos-mfa.md` | +| Configure email delivery | `references/workos-email.md` | +| Set up Custom Domains | `references/workos-custom-domains.md` | +| Set up IdP integration | `references/workos-integrations.md` | +| Implement FGA / fine-grained authz | `references/workos-fga.md` | +| Set up Pipes / Connected Apps | `references/workos-pipes.md` | +| Configure Feature Flags | `references/workos-feature-flags.md` | +| Set up Radar / fraud detection | `references/workos-radar.md` | ### API References (Read `references/{name}.md`) @@ -101,9 +128,9 @@ Feature topic files above include endpoint tables for their respective APIs. Use ### Management & CLI Lifecycle (Read `references/{name}.md`) -| User wants to... | Read file | -| ---------------------------------------- | ---------------------------------- | -| Manage WorkOS resources via CLI commands | `references/workos-management.md` | +| User wants to... | Read file | +| ------------------------------------------- | ---------------------------------- | +| Manage WorkOS resources via CLI commands | `references/workos-management.md` | | Upgrade the `workos` CLI to a newer version | `references/workos-cli-upgrade.md` | ## Routing Decision Tree From 84d0588008e62b361cc641f029401f0252b08e3c Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Sun, 10 May 2026 13:49:28 -0500 Subject: [PATCH 2/4] fix(workos): tighten agent-mode guidance for precision and rot-resistance Reframe guardrail as prohibition, explain --skip-ai flag, add --help fallback for confirmation flags, clarify WORKOS_NO_PROMPT migration path, and remove redundant parenthetical from widgets workflow. --- plugins/workos/skills/workos-widgets/SKILL.md | 2 +- plugins/workos/skills/workos/SKILL.md | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/plugins/workos/skills/workos-widgets/SKILL.md b/plugins/workos/skills/workos-widgets/SKILL.md index ab594a3..5d4c75e 100644 --- a/plugins/workos/skills/workos-widgets/SKILL.md +++ b/plugins/workos/skills/workos-widgets/SKILL.md @@ -16,7 +16,7 @@ description: Use when the user is implementing, embedding, or debugging a WorkOS 3. Detect stack, data-layer style, styling, component system, and package manager using [references/detection.md](references/detection.md). 4. Check for AuthKit/WorkOS presence: - if detected, continue; - - if not detected, ask the user to run `WORKOS_MODE=agent npx workos@latest install` (agent mode keeps the installer non-interactive and surfaces structured errors with recovery hints). Wait for confirmation, then continue. + - if not detected, ask the user to run `WORKOS_MODE=agent npx workos@latest install`. Wait for confirmation, then continue. 5. If detection is ambiguous or conflicting, ask one focused question, then continue. 6. Load only the relevant reference files for the detected stack and widget. 7. Implement integration based on stack shape: diff --git a/plugins/workos/skills/workos/SKILL.md b/plugins/workos/skills/workos/SKILL.md index 3fe5c16..d9969ac 100644 --- a/plugins/workos/skills/workos/SKILL.md +++ b/plugins/workos/skills/workos/SKILL.md @@ -20,7 +20,7 @@ description: Use when the user asks for a WorkOS docs URL, term, or dashboard fi These apply regardless of which routing rule fires. They exist because the most common failure mode of past WorkOS agent interactions has been plausibly-shaped fabrication of CLI commands and Dashboard paths. - **Never invent `workos` CLI commands.** If the user asks about CLI support or you're about to suggest a command, verify the command tree first. The authoritative source is `WORKOS_MODE=agent workos --help --json` — it emits the complete registered command tree. Do not assume a `create` subcommand exists because `list`/`get`/`delete` do. See `references/workos-management.md`. -- **Run the `workos` CLI in agent mode.** When invoking the CLI from a coding-agent session, prefix commands with `WORKOS_MODE=agent` (e.g. `WORKOS_MODE=agent workos doctor --json --skip-ai`). Agent mode controls prompts, browser fallback, and host trust; `--json` controls output formatting only. See the **WorkOS CLI in Coding-Agent Sessions** section below. +- **Never run the `workos` CLI without `WORKOS_MODE=agent` in a coding-agent session.** Without it, commands may launch a browser, prompt for input, or trust the host environment — all of which fail silently in sandboxes. See the **WorkOS CLI in Coding-Agent Sessions** section below. - **Never invent Dashboard click-paths.** Phrases like "Dashboard > Organizations > X > Roles > Map Groups" or `dashboard.workos.com/some/specific/path` should not appear unless you have verified them against a docs page you just fetched. The Dashboard UI reorganizes; docs pages are stable. Cite the docs URL and describe the destination conceptually ("the Authorization page", "the directory's settings") instead of committing to a click-path. - **When the user wants to do something not supported by the CLI, say so plainly.** Users are better served by "this isn't in the CLI; here's the docs URL for how to do it" than by a fabricated command that fails. See the "Not in the CLI" section of `references/workos-management.md`. - **Prefer docs URLs over prose when writing recipes.** If a reference file tells you to cite a specific docs URL, cite it literally; don't paraphrase the URL's slug. @@ -35,6 +35,8 @@ When using the `workos` CLI from a coding agent, treat output mode and interacti WORKOS_MODE=agent workos doctor --json --skip-ai ``` +`--skip-ai` disables the doctor's AI-powered diagnosis pass, which requires an API key and network round-trip — neither is guaranteed in a sandbox. The structured JSON output is sufficient for programmatic triage. + This returns a structured JSON report including an `interactionMode` field (`{ mode, source }`) and a `hostExecution` block. Read the JSON before suggesting fixes. **Rules:** @@ -43,12 +45,12 @@ This returns a structured JSON report including an `interactionMode` field (`{ m - Use `WORKOS_MODE=agent` even when relaying human-readable messages. It controls **prompts, browser launch, and host trust**. - Treat the doctor `HOST_EXECUTION_UNTRUSTED` issue as a hard trust boundary. If the doctor report contains this issue (or `hostExecution.ok` is `false`), **the current shell may be sandboxed**. Auth, config, keychain, and API failures from this shell are not authoritative. Ask the user to re-run host-sensitive commands (`workos auth login`, `workos doctor`, `workos env add`) on their host shell before drawing conclusions. - Do not assume browser-based auth (`workos auth login`) works in a sandbox. If auth is required, surface the manual URL/code fallback that the CLI prints, or ask the user to run `workos auth login` on their host shell. -- For destructive CLI commands in agent mode, pass the explicit confirmation flag (`--yes` for `workos api`, `--force` for `workos connection delete`, `workos directory delete`, etc.). Agent mode never prompts. +- For destructive CLI commands in agent mode, pass the explicit confirmation flag (e.g. `--yes` for `workos api`, `--force` for `workos connection delete`). Agent mode never prompts, so omitting the flag causes the command to fail. If unsure which flag a command expects, run `workos --help --json` to check. - Structured CLI errors include an optional `error.recovery.hints[]` array with the next deterministic command to run. Prefer those hints over guessing. **Legacy compatibility you may encounter:** -- `WORKOS_NO_PROMPT=1` is a legacy alias for agent interaction behavior plus JSON output. Prefer `WORKOS_MODE=agent` in new instructions. +- `WORKOS_NO_PROMPT=1` is a legacy alias that sets both agent interaction behavior AND JSON output. To migrate, replace it with `WORKOS_MODE=agent --json` to preserve both behaviors. Using `WORKOS_MODE=agent` alone drops the implicit JSON formatting. - `WORKOS_FORCE_TTY=1` only affects output formatting; it does not change interaction mode. ## Topic → Reference Map From 91683553fe3618b71e29edc268e00c499c41032a Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Sun, 10 May 2026 13:52:50 -0500 Subject: [PATCH 3/4] fix(workos): address second-pass review findings - Fix broken WORKOS_NO_PROMPT migration syntax (was not a runnable fragment) - Add CLI/agent-mode/doctor to skill description for triggering - Drop "machine-readable" framing from widgets to avoid implying agent mode replaces --json - Add --skip-ai version fallback to cli-upgrade reference - Soften doctor JSON shape claims to resist schema rot --- plugins/workos/skills/workos-widgets/SKILL.md | 2 +- plugins/workos/skills/workos/SKILL.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/plugins/workos/skills/workos-widgets/SKILL.md b/plugins/workos/skills/workos-widgets/SKILL.md index 5d4c75e..0c43c15 100644 --- a/plugins/workos/skills/workos-widgets/SKILL.md +++ b/plugins/workos/skills/workos-widgets/SKILL.md @@ -99,7 +99,7 @@ Then load exactly one widget reference: - Implement a consistent authorization layer for widget requests, including elevated-token handling for sensitive endpoints when required. - If the app already uses React Query or SWR, use them as orchestration/cache layers around those direct calls. - For React/TypeScript widget code quality expectations, follow [references/react-ts-standards.md](references/react-ts-standards.md). -- If AuthKit/WorkOS is missing, prompt the user to run `WORKOS_MODE=agent npx workos@latest install` before continuing. `WORKOS_MODE=agent` keeps the installer deterministic and machine-readable in agent sessions; `--json` may be added when you need to parse output. +- If AuthKit/WorkOS is missing, prompt the user to run `WORKOS_MODE=agent npx workos@latest install` before continuing. `WORKOS_MODE=agent` keeps the installer deterministic (no prompts, no browser, no host-trust); pass `--json` when you need to parse the output. - Install additional dependencies only when strictly necessary, using the detected package manager/tooling. - Keep server-state handling aligned with the selected data-layer approach. - Use local state/reducers for UI interaction state as needed. diff --git a/plugins/workos/skills/workos/SKILL.md b/plugins/workos/skills/workos/SKILL.md index d9969ac..b44eae8 100644 --- a/plugins/workos/skills/workos/SKILL.md +++ b/plugins/workos/skills/workos/SKILL.md @@ -1,6 +1,6 @@ --- name: workos -description: Use when the user asks for a WorkOS docs URL, term, or dashboard field (Sign-in endpoint, initiate_login_uri, Redirect URI, `WORKOS_*` env vars), or is implementing, debugging, or migrating WorkOS — AuthKit, SSO/SAML, Directory Sync, RBAC, FGA, MFA, Vault, Audit Logs, Admin Portal, Pipes (Connected Apps), Feature Flags, Radar (bot/fraud detection), webhooks, Custom Domains, or migrating from Auth0, Clerk, Cognito, Firebase, Supabase, Stytch, Descope, or Better Auth. Also triggers on @workos-inc/* imports. +description: Use when the user asks for a WorkOS docs URL, term, or dashboard field (Sign-in endpoint, initiate_login_uri, Redirect URI, `WORKOS_*` env vars), or is implementing, debugging, or migrating WorkOS — AuthKit, SSO/SAML, Directory Sync, RBAC, FGA, MFA, Vault, Audit Logs, Admin Portal, Pipes (Connected Apps), Feature Flags, Radar (bot/fraud detection), webhooks, Custom Domains, running the `workos` CLI in agent or sandbox sessions (`WORKOS_MODE`, `workos doctor`), or migrating from Auth0, Clerk, Cognito, Firebase, Supabase, Stytch, Descope, or Better Auth. Also triggers on @workos-inc/* imports. --- # WorkOS Skill Router @@ -35,9 +35,9 @@ When using the `workos` CLI from a coding agent, treat output mode and interacti WORKOS_MODE=agent workos doctor --json --skip-ai ``` -`--skip-ai` disables the doctor's AI-powered diagnosis pass, which requires an API key and network round-trip — neither is guaranteed in a sandbox. The structured JSON output is sufficient for programmatic triage. +`--skip-ai` disables the doctor's AI-powered diagnosis pass, which requires an API key and network round-trip — neither is guaranteed in a sandbox. If `--skip-ai` errors as an unknown flag, the CLI is outdated — see `references/workos-cli-upgrade.md`. The structured JSON output is sufficient for programmatic triage. -This returns a structured JSON report including an `interactionMode` field (`{ mode, source }`) and a `hostExecution` block. Read the JSON before suggesting fixes. +This returns a structured JSON report. Look for fields indicating interaction mode (e.g. `interactionMode`) and host execution status (e.g. `hostExecution`). If the JSON shape differs from what's described here, trust the output schema — it's the source of truth. **Rules:** @@ -50,7 +50,7 @@ This returns a structured JSON report including an `interactionMode` field (`{ m **Legacy compatibility you may encounter:** -- `WORKOS_NO_PROMPT=1` is a legacy alias that sets both agent interaction behavior AND JSON output. To migrate, replace it with `WORKOS_MODE=agent --json` to preserve both behaviors. Using `WORKOS_MODE=agent` alone drops the implicit JSON formatting. +- `WORKOS_NO_PROMPT=1` is a legacy alias that sets both agent interaction behavior AND JSON output. To migrate, set `WORKOS_MODE=agent` and pass `--json` to the command to preserve both behaviors. Using `WORKOS_MODE=agent` alone drops the implicit JSON formatting. - `WORKOS_FORCE_TTY=1` only affects output formatting; it does not change interaction mode. ## Topic → Reference Map From 2fbd7dbaf7a9a5a9500740a2fa17ed468e5c7663 Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Wed, 13 May 2026 14:43:29 -0500 Subject: [PATCH 4/4] fix(workos): align agent-mode guidance with shipped CLI implementation - Soften guardrail from "never run without" to "prefer" since the CLI auto-detects CLAUDECODE, CLAUDE_CODE, CURSOR_AGENT, CODEX_SANDBOX, CURSOR_TRACE_ID, and non-TTY - Document the two-axis model (interaction mode vs output mode) with the three possible interaction values (human/agent/ci) - Restore precise doctor field names (interactionMode, hostExecution) since they're stable type definitions in the CLI - Fix recovery hints shape: describe per-hint fields (description, command, hostShellRequired) and note JSON is emitted on stderr - Enumerate all known confirmation flags including debug reset --- plugins/workos/skills/workos/SKILL.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/plugins/workos/skills/workos/SKILL.md b/plugins/workos/skills/workos/SKILL.md index b44eae8..2b893b1 100644 --- a/plugins/workos/skills/workos/SKILL.md +++ b/plugins/workos/skills/workos/SKILL.md @@ -20,14 +20,14 @@ description: Use when the user asks for a WorkOS docs URL, term, or dashboard fi These apply regardless of which routing rule fires. They exist because the most common failure mode of past WorkOS agent interactions has been plausibly-shaped fabrication of CLI commands and Dashboard paths. - **Never invent `workos` CLI commands.** If the user asks about CLI support or you're about to suggest a command, verify the command tree first. The authoritative source is `WORKOS_MODE=agent workos --help --json` — it emits the complete registered command tree. Do not assume a `create` subcommand exists because `list`/`get`/`delete` do. See `references/workos-management.md`. -- **Never run the `workos` CLI without `WORKOS_MODE=agent` in a coding-agent session.** Without it, commands may launch a browser, prompt for input, or trust the host environment — all of which fail silently in sandboxes. See the **WorkOS CLI in Coding-Agent Sessions** section below. +- **Prefer `WORKOS_MODE=agent` when invoking the `workos` CLI from a coding-agent session.** The CLI auto-detects most agent environments (`CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_AGENT`, `CODEX_SANDBOX`, non-TTY), but the explicit env var is more reliable across sandbox configurations. See the **WorkOS CLI in Coding-Agent Sessions** section below. - **Never invent Dashboard click-paths.** Phrases like "Dashboard > Organizations > X > Roles > Map Groups" or `dashboard.workos.com/some/specific/path` should not appear unless you have verified them against a docs page you just fetched. The Dashboard UI reorganizes; docs pages are stable. Cite the docs URL and describe the destination conceptually ("the Authorization page", "the directory's settings") instead of committing to a click-path. - **When the user wants to do something not supported by the CLI, say so plainly.** Users are better served by "this isn't in the CLI; here's the docs URL for how to do it" than by a fabricated command that fails. See the "Not in the CLI" section of `references/workos-management.md`. - **Prefer docs URLs over prose when writing recipes.** If a reference file tells you to cite a specific docs URL, cite it literally; don't paraphrase the URL's slug. ## WorkOS CLI in Coding-Agent Sessions -When using the `workos` CLI from a coding agent, treat output mode and interaction mode as separate axes and set both explicitly. The CLI's auto-detection works, but explicit flags are more reliable across sandboxes. +The CLI resolves two independent axes: **interaction mode** (`human`/`agent`/`ci`) and **output mode** (`human`/`json`). The CLI auto-detects agent environments via known env vars (`CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_AGENT`, `CODEX_SANDBOX`, `CURSOR_TRACE_ID`) and non-TTY detection, but explicit settings are more reliable across sandbox configurations. **Recommended preflight for any setup or debugging task:** @@ -37,7 +37,7 @@ WORKOS_MODE=agent workos doctor --json --skip-ai `--skip-ai` disables the doctor's AI-powered diagnosis pass, which requires an API key and network round-trip — neither is guaranteed in a sandbox. If `--skip-ai` errors as an unknown flag, the CLI is outdated — see `references/workos-cli-upgrade.md`. The structured JSON output is sufficient for programmatic triage. -This returns a structured JSON report. Look for fields indicating interaction mode (e.g. `interactionMode`) and host execution status (e.g. `hostExecution`). If the JSON shape differs from what's described here, trust the output schema — it's the source of truth. +This returns a structured JSON report with `interactionMode` (`{ mode, source }`) and `hostExecution` (`{ ok, failures[] }`) fields. Read the JSON before suggesting fixes. **Rules:** @@ -45,8 +45,8 @@ This returns a structured JSON report. Look for fields indicating interaction mo - Use `WORKOS_MODE=agent` even when relaying human-readable messages. It controls **prompts, browser launch, and host trust**. - Treat the doctor `HOST_EXECUTION_UNTRUSTED` issue as a hard trust boundary. If the doctor report contains this issue (or `hostExecution.ok` is `false`), **the current shell may be sandboxed**. Auth, config, keychain, and API failures from this shell are not authoritative. Ask the user to re-run host-sensitive commands (`workos auth login`, `workos doctor`, `workos env add`) on their host shell before drawing conclusions. - Do not assume browser-based auth (`workos auth login`) works in a sandbox. If auth is required, surface the manual URL/code fallback that the CLI prints, or ask the user to run `workos auth login` on their host shell. -- For destructive CLI commands in agent mode, pass the explicit confirmation flag (e.g. `--yes` for `workos api`, `--force` for `workos connection delete`). Agent mode never prompts, so omitting the flag causes the command to fail. If unsure which flag a command expects, run `workos --help --json` to check. -- Structured CLI errors include an optional `error.recovery.hints[]` array with the next deterministic command to run. Prefer those hints over guessing. +- For destructive CLI commands in agent mode, pass the explicit confirmation flag. Agent mode never prompts, so omitting the flag causes a `confirmation_required` error. Known flags: `--yes` for `workos api` (mutating methods), `--force` for `workos connection delete`, `workos directory delete`, and `workos debug reset`. If unsure which flag a command expects, run `workos --help --json` to check. +- Structured CLI errors (JSON on stderr) include an optional `error.recovery.hints` array, where each hint has `description`, optional `command`, and optional `hostShellRequired`. Prefer those hints over guessing the next step. **Legacy compatibility you may encounter:**