feat(migrate): add migration command suite

.changeset/integrate-migration-tool-into-cli.md

@@ -0,0 +1,12 @@
+---
+"clerk": minor
+---
+
+Add `clerk migrate` for moving users into Clerk from Clerk, Auth0, Supabase, Auth.js, Better Auth, Firebase or WorkOS.
+
+- `migrate export <source>` writes a self-describing file. `migrate import <file|export-run-id>` checks every user against the instance before writing (`--dry-run`, `--allow-partial`, `--skip-legal-checks`), asks before it writes, and continues where an interrupted or partial run stopped.
+- `migrate runs` shows what every run did, `migrate undo <run-id>` deletes the users an import created, and `migrate sources` shows what each source carries, including sources you write yourself (`--source ./my-source.ts`).
+- A request that cannot connect now names the host it could not reach.
+- `clerk init` warns when the project uses WorkOS, and points to the migration guide.
+- Multiselect prompts list `a: all` in their key legend.
+- `clerk users` dry runs name the instance the key reaches and where the key came from, such as `--app` or the `CLERK_SECRET_KEY` env var.

.github/workflows/ci.yml

@@ -45,7 +45,7 @@ jobs:
           key: bun-${{ runner.os }}-${{ hashFiles('bun.lock') }}
           restore-keys: bun-${{ runner.os }}-
       - run: bun install --frozen-lockfile
-      - run: bun run build
+      - run: bun run build:compile
 
   lint:
     name: Lint

.gitignore

@@ -12,6 +12,8 @@ coverage
 
 # logs
 logs
+!packages/cli-core/src/commands/migrate/logs/
+!packages/cli-core/src/commands/migrate/logs/**
 _.log
 report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
@@ -44,3 +46,7 @@ test/e2e/.har
 
 # Local planning/spec docs
 docs/superpowers/
+
+# Local migration exports and the credentials that produced them
+exports/
+*service-account*.json

CLAUDE.md

@@ -30,7 +30,7 @@ Default to using Bun instead of Node.js.
 - `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
 - `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
 - `Bun.redis` for Redis. Don't use `ioredis`.
-- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `Bun.sql` for Postgres and MySQL. Don't use `pg`, `postgres.js`, or `mysql2`.
 - `WebSocket` is built-in. Don't use `ws`.
 - Prefer `Bun.file` over `node:fs`'s readFile/writeFile
 - Bun.$`ls` instead of execa.
@@ -48,14 +48,16 @@ bun run test:e2e:op  # Run E2E tests with secrets resolved from 1Password (prefe
 bun run test:e2e     # Run E2E tests with env vars already set (used by CI)
 ```
 
-Locally, prefer `bun run test:e2e:op` so secrets are injected from 1Password in-memory and never written to disk. `bun run test:e2e` is for CI or for cases where the required env vars are already exported.
+Locally, prefer `bun run test:e2e:op` so secrets are injected from 1Password in-memory and never written to disk. `bun run test:e2e` is for CI or for cases where the required env vars are already exported. Both run `bun test` with `--no-env-file`, so a `.env.local` pointing the CLI at a local `clerk_go` stack can't send the production test secrets there.
 
 CI runs `bun run format:check` (fails if unformatted), `bun run lint`, `bun run test`, and `bun run test:e2e` on every PR to `main`. E2E tests only run for PRs from the same repository (not external forks) and target the production Clerk API with a dedicated test application.
 
 When running multiple test files directly with `bun test`, always pass `--isolate` or `--parallel`. `--parallel` implies `--isolate`. Without isolation, Bun can share module mocks across files and produce order-dependent failures. Prefer `bun run test` for the full suite because it already passes `--parallel`.
 
 These flags require Bun >= 1.3.13 — older versions silently ignore them and lose isolation. `bun run test` and `bun run test:e2e` run `scripts/check-bun-version.ts` first, which fails fast when the installed Bun is older than the `engines.bun` floor in package.json.
 
+The same floor also covers `Bun.sql`'s MySQL adapter used by the DB-backed export commands: MySQL support landed in Bun 1.2.21, but binary columns (password hashes) only decoded correctly from 1.3.6. See the header of `scripts/check-bun-version.ts`.
+
 ## Versioning
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.

README.md

@@ -86,6 +86,7 @@ Commands:
   init             [options]                      Initialize Clerk in your project
   link             [options]                      Link this project to a Clerk application
   mcp                                             Manage the Clerk remote MCP server connection for AI editors and CLIs
+  migrate                                         Migrate users into Clerk from another auth provider or another Clerk instance
   open                                            Open Clerk resources in your browser
   telemetry                                       Control CLI usage telemetry (status, disable, enable)
   unlink           [options]                      Unlink this project from its Clerk application