workos 0.15.2 → 0.17.0

package/README.md

@@ -23,6 +23,7 @@ shell command cache.
 - **AI-Powered:** Uses Claude to intelligently adapt to your project structure
 - **Security-First:** Masks API keys, redacts from logs, saves to .env.local
 - **Smart Detection:** Auto-detects framework, package manager, router type
+- **Greenfield Scaffolding:** Run in an empty directory to scaffold a new Next.js app (via `create-next-app`) before wiring AuthKit
 - **Live Documentation:** Fetches latest SDK docs from WorkOS and GitHub
 - **Full Integration:** Creates routes, middleware, environment vars, and UI
 - **Agent & CI Ready:** Non-TTY auto-detection, JSON output, structured errors, headless installer with NDJSON streaming
@@ -81,6 +82,9 @@ Resource Management:
   api-key                Manage per-org API keys
   org-domain             Manage organization domains
 
+Migrations:
+  migrations             Migrate users and SSO connections into WorkOS
+
 Workflows:
   seed                   Declarative resource provisioning from YAML
   setup-org              One-shot organization onboarding
@@ -196,6 +200,27 @@ Inspects a directory's sync state, user/group counts, recent events, and detects
 workos debug-sync directory_01ABC123
 ```
 
+### Migrations
+
+Migrate users and SSO connections from other identity providers into WorkOS. The `migrations` namespace passes through to `@workos/migrations`.
+
+```bash
+# Interactive migration wizard
+workos migrations wizard
+
+# Export a blank CSV template
+workos migrations export-template saml_connections --output saml_connections.csv
+workos migrations export-template oidc_connections --output oidc_connections.csv
+
+# Export from Auth0
+workos migrations export-auth0 --domain your-tenant.auth0.com --client-id <id> --client-secret <secret>
+
+# Import users from CSV
+workos migrations import --csv users.csv
+```
+
+Run `workos migrations --help` for all available subcommands.
+
 <!-- UNRELEASED: Local Development (emulator) — hidden until beta testing is complete.
      To restore, uncomment this section and re-enable the `emulate` and `dev` commands
      in src/bin.ts and src/utils/help-json.ts.
@@ -512,13 +537,14 @@ workos portal generate-link --intent <intent> --org <orgId> [--return-url] [--su
 
 ```bash
 workos vault list [--limit]
-workos vault get <id>
-workos vault get-by-name <name>
-workos vault create --name <name> --value <secret> [--org <orgId>]
-workos vault update <id> --value <secret> [--version-check]
+workos vault get <id> [--decrypt]
+workos vault get-by-name <name> [--decrypt]
+workos vault create --name <name> --org <orgId> [--value <secret>]   # omit --value to read from stdin
+workos vault update <id> [--value <secret>] [--version-check]        # omit --value to read from stdin
 workos vault delete <id>
 workos vault describe <id>
 workos vault list-versions <id>
+workos vault run --secret ENV_VAR=vault-name [...] [--env <name>] [--dry-run] -- <command>
 ```
 
 #### api-key
@@ -545,12 +571,13 @@ workos org-domain delete <id>
 workos install [options]
 
   --direct, -D            Use your own Anthropic API key (bypass llm-gateway)
-  --integration <name>    Framework: nextjs, react, react-router, tanstack-start, vanilla-js, sveltekit, node, python, ruby, go, dotnet, kotlin, elixir, php-laravel, php
   --api-key <key>         WorkOS API key (required in non-interactive mode)
   --client-id <id>        WorkOS client ID (required in non-interactive mode)
   --redirect-uri <uri>    Custom redirect URI
   --homepage-url <url>    Custom homepage URL
   --install-dir <path>    Installation directory
+  --scaffold              Scaffold a new Next.js app when run in an empty directory
+  --pm <manager>          Package manager for the scaffolded app: npm, pnpm, yarn, bun
   --no-validate           Skip post-installation validation
   --no-branch             Skip branch creation (use current branch)
   --no-commit             Skip auto-commit after installation
@@ -560,14 +587,16 @@ workos install [options]
   --debug                 Enable verbose logging
 ```
 
+**Empty directories:** Running `workos install` in an empty directory scaffolds a new Next.js app with `create-next-app` (App Router, TypeScript, Tailwind, `src/`) and then wires AuthKit into it. This only happens when the directory is empty or contains nothing but VCS/editor metadata (`.git`, `.gitignore`, `LICENSE`, `.idea`, and similar). Any project file — including a `README.md` or a `package.json` — opts out, and the installer treats the directory as an existing project. Interactive runs confirm first (default yes); non-interactive/headless runs (or `--scaffold`) scaffold automatically and report `"scaffolded": true`. The package manager is resolved from how you invoked the CLI (`npm_config_user_agent`) unless you pass `--pm`.
+
 ## Examples
 
 ```bash
 # Interactive (recommended)
 npx workos@latest install
 
-# Specify framework
-npx workos@latest install --integration react-router
+# Greenfield: scaffold a new Next.js app + AuthKit in an empty directory
+mkdir my-app && cd my-app && npx workos@latest install
 
 # With visual dashboard (experimental)
 npx workos@latest dashboard
@@ -712,17 +741,18 @@ OAuth credentials are stored in the system keychain (with `~/.workos/credentials
 
 ## Telemetry
 
-The installer collects anonymous usage telemetry to help improve the product:
+The CLI collects anonymous usage telemetry to help improve the product:
+
+- **Command events** -- command name, duration, success/failure, termination reason, and which flags were used (for telemetry-enabled commands; `install` and `dashboard` use session events instead)
+- **Session events** -- framework detected, step timing, token usage (installer only)
+- **Crash events** -- sanitized error type and stack trace (no secrets, truncated to 4KB)
 
-- Session outcome (success/error/cancelled)
-- Framework detected
-- Duration and step timing
-- Token usage (for capacity planning)
+Environment fingerprint (OS, Node version, shell, CI detection) is included on all events. No code, credentials, or personal data is collected.
 
-No code, credentials, or personal data is collected. Disable with:
+Disable with:
 
 ```bash
-WORKOS_TELEMETRY=false npx workos@latest install
+WORKOS_TELEMETRY=false workos <command>
 ```
 
 ## Logs