feat: add env provision + verify-login commands, fix non-interactive installs (agent/CI), Vite port detection, and misleading command hints

[nicknisi]

Fixes every CLI-side item from Akshay Maniyar's AuthKit Hybrid + Full Agent friction log. Six implementation commits (plus a formatting pass), each independently gate-tested (pnpm build && pnpm test && pnpm typecheck green at every commit; final suite 2,310 tests).

Agent/CI path — 36c47e9

• Bare npx workos in a non-TTY shell now emits the full JSON command tree on stdout (exit 0) instead of a degenerate two-option help dump (the old handler called showHelp() on a fresh yargs instance with no commands registered).
• abortIfCancelled fails fast with a structured non_interactive_prompt error when prompts are disallowed — any future unguarded prompt dies loudly instead of hanging an agent forever.
• New --router app|pages flag (flag wins); without it, ambiguous Next.js router detection defaults to app router with a warning in non-interactive mode. Same graceful defaults for React Router's ambiguous branches and the upload-env prompt.
• WORKOS_MODE=ci now enforces the same behavior as the hidden --ci flag (dirty-tree auto-continue, package-manager auto-select) — previously two disconnected notions of "CI".

Port detection + validation — aa875e3

• detectPort parses vite.config.{ts,js,mjs} first for TanStack Start (Lovable shape), with legacy app.config.ts fallback. Previously the installer wrote port 3000 into .env.local and the dashboard (redirect/CORS/homepage) for an app running on 8080.
• All three JS redirect validators now flag a redirect-URI/dev-port mismatch on local hosts as a validation error — no more "Validation passed" over a broken install. Remediation hints use the real redirect origin instead of hardcoded localhost:3000.
• The 11 new regression tests were stash-verified to fail on pre-fix code.

Messaging sweep — bb2c2b1

• ~28 live hardcoded workos <subcommand> hints routed through the npx-aware formatWorkOSCommand helper, enforced by a new repo-walk regression guard with a curated allowlist — new hardcoded hints fail pnpm test.
• "Using provided WorkOS credentials" only renders when the user actually provided credentials (source threaded to both adapters).
• env remove help states it is local-config-only; env claim states claiming is permanent; migrations description reframed around the CSV path (e.g. Supabase) via a shared constant.

Install UX — f6c81d0

• Post-install summary no longer discards the rich summary on success: a pure buildCompletionData builder assembles the lockfile-aware dev command, app URL with detected port, changed files, next steps, and per-framework docs/dashboard URLs, rendered by all three adapters (CLI/Dashboard/Headless) with a static fallback.
• Removed the 2s setInterval that clobbered agent phase text; file:write/file:edit events stream as append-only step lines (CLI) and NDJSON (headless). Stretch: agent:tool Bash surfacing + a Next.js sign-in-link snippet.

Env provision + login safety — f3452cb

• workos env provision: credentials-only unclaimed environment (apiKey/clientId/claimToken via --json), no code-gen, no project writes — closes the agent workaround of running install in throwaway directories just to extract keys.
• auth login never silently repoints the active environment to a different account: mismatches (ownerEmail/clientId comparison) prompt in human mode, warn in agent/JSON mode, and every login ends with Now using: <env> (<email>).

verify-login — 738d8cc

• workos verify-login proves the AuthKit loop headlessly: throwaway user → authenticateWithPassword → token assertion → deleteUser in a finally block. Unconditional production refusal (env type or sk_live_ prefix) before any SDK call, no override flag. 13 spec cases; live smoke-tested against the real API.

Merge note

Prefer rebase merge over squash: the commits are conventional-commit formatted (fix:/feat:), so release-please picks up each as its own changelog entry. A squash would collapse them into one line.

[greptile-apps]

This review was skipped because it would exceed your organization's monthly flex usage limit. Raise the limit in billing settings or wait until the next billing period resets limits.

[devin-ai-integration]

Devin Review found 1 potential issue.

[devin-ai-integration]

🔍 Silent overwrite of existing unclaimed environment on repeated provision

The runEnvProvision function (src/commands/env.ts:153-162) unconditionally writes to the 'unclaimed' config key. If a user runs workos env provision twice without claiming the first environment, the first environment's claim token is silently replaced. The old claim token is permanently lost — there is no way to recover or claim that first environment. This is arguably by design (the test at src/commands/env.spec.ts:308-319 verifies the overwrite), but it could surprise agents that provision environments speculatively. A guard or warning before overwriting an existing unclaimed entry would make the behavior explicit.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[nicknisi]

Fixed in ea953b0. env provision (and the install auto-provision path in unclaimed-env-provision.ts, which had the same clobber) now allocate a fresh key (unclaimed, unclaimed-2, …) via a shared freshEnvKey() helper, so an earlier environment's claim token is never destroyed. The newest env becomes active; earlier ones stay claimable via env switch + env claim. Regression tests cover both paths (provision twice → first claim token preserved, second env active).

[greptile-apps]

Greptile Summary

This PR expands the WorkOS CLI's agent and install workflows. The main changes are:

• Adds non-interactive command-tree output for bare CLI invocations.
• Adds env provision for credentials-only unclaimed environment setup.
• Adds verify-login for headless AuthKit password-loop checks.
• Improves CI-mode defaults, prompt handling, and router detection.
• Adds Vite/TanStack port detection and redirect port validation.
• Updates install completion output and npx-aware command hints.

Confidence Score: 5/5

Safe to merge based on the reviewed changed paths.

No new blocking issues were identified in the command, provisioning, validation, completion, and non-interactive flows reviewed.

src/commands/login.ts has an existing active-account message thread already on the PR; no new files need special attention.

T-Rex Logs

What T-Rex did

• Ran the Vitest suite in the repository and confirmed all tests passed, reporting 10 test files and 172 tests in total.
• Executed the CLI in CI mode to generate a JSON manifest and confirmed stdout starts with a structured JSON object containing CLI metadata.
• Executed the CLI help command in CI mode and confirmed the output shows the help command tree and options without hanging.
• Uploaded four artifacts capturing the vitest results and CLI outputs to support review.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
src/bin.ts	Registers verify-login/env provision, router flag, JSON help behavior, and npx-aware command hints.
src/commands/env.ts	Implements credentials-only unclaimed env provisioning and clearer local removal behavior.
src/commands/login.ts	Adds account ownership stamping and mismatch handling; previous active-account reporting concern remains out of scope for duplicate comments.
src/commands/verify-login.ts	Introduces headless AuthKit password-loop verification with production-key refusal and cleanup.
src/lib/adapters/headless-adapter.ts	Streams file/tool events and enriched completion data as NDJSON.
src/lib/port-detection.ts	Parses Vite config ports before framework defaults/fallbacks.
src/lib/run-with-core.ts	Threads credential sources, detected ports, and completion data through the core runner.
src/lib/validation/validator.ts	Adds local redirect URI port validation for JS frameworks.
src/utils/clack-utils.ts	Adds structured non_interactive_prompt failure and invocation-aware prompt hints.
src/utils/help-json.ts	Updates static command tree with new commands/options and descriptions.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
  participant User as User/Agent
  participant CLI as workos CLI
  participant Config as Config Store
  participant API as WorkOS API
  participant Validator as Install Validator

  User->>CLI: env provision / install / verify-login
  alt env provision
    CLI->>API: POST /x/one-shot-environments
    API-->>CLI: apiKey, clientId, claimToken, authkitDomain
    CLI->>Config: save fresh unclaimed env as active
    CLI-->>User: JSON or human credentials + env claim hint
  else install non-interactive
    CLI->>Config: resolve active/provided credentials
    CLI->>Validator: detect framework + dev port
    Validator-->>CLI: redirect/port validation issues or pass
    CLI-->>User: NDJSON progress + completion data
  else verify-login
    CLI->>Config: read active env metadata
    CLI->>API: create throwaway user
    CLI->>API: authenticateWithPassword
    CLI->>API: deleteUser in finally
    CLI-->>User: verification result
  end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
  participant User as User/Agent
  participant CLI as workos CLI
  participant Config as Config Store
  participant API as WorkOS API
  participant Validator as Install Validator

  User->>CLI: env provision / install / verify-login
  alt env provision
    CLI->>API: POST /x/one-shot-environments
    API-->>CLI: apiKey, clientId, claimToken, authkitDomain
    CLI->>Config: save fresh unclaimed env as active
    CLI-->>User: JSON or human credentials + env claim hint
  else install non-interactive
    CLI->>Config: resolve active/provided credentials
    CLI->>Validator: detect framework + dev port
    Validator-->>CLI: redirect/port validation issues or pass
    CLI-->>User: NDJSON progress + completion data
  else verify-login
    CLI->>Config: read active env metadata
    CLI->>API: create throwaway user
    CLI->>API: authenticateWithPassword
    CLI->>API: deleteUser in finally
    CLI-->>User: verification result
  end

Loading

_{Reviews (5): Last reviewed commit: "refactor: apply code-quality review clea..." | Re-trigger Greptile}

[nicknisi]

Re greptile's dirty-tree finding: confirmed real — the legacy --ci auto-continue lived in clack-utils.ts helpers that nothing calls anymore, so CI-mode headless installs still exited on a dirty tree unless --no-git-check was passed. Fixed in ea953b0: ci is now threaded into the HeadlessAdapter (run-with-core.ts), and CI mode auto-continues the git check (NDJSON git:decision: continue). Agent mode intentionally keeps the strict gate, since a dirty tree there is usually the user's own uncommitted work. Regression test added in headless-adapter.spec.ts; CLAUDE.md's non-TTY section updated to document the split.