feat(migrate): add migration command suite

.changeset/migrate-cli.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk migrate` for importing users with `migrate import`, exporting from supported auth providers, reviewing migration logs, undoing a migration, and extending imports with custom transformers.

.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.
@@ -56,6 +56,8 @@ When running multiple test files directly with `bun test`, always pass `--isolat
 
 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

@@ -48,6 +48,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
   open                                            Open Clerk resources in your browser
   telemetry                                       Control CLI usage telemetry (status, disable, enable)
   unlink           [options]                      Unlink this project from its Clerk application

packages/cli-core/package.json

@@ -22,11 +22,13 @@
     "@commander-js/extra-typings": "^15.0.0",
     "@napi-rs/keyring": "^1.3.0",
     "commander": "^15.0.0",
+    "csv-parser": "^3.2.1",
     "env-paths": "^4.0.0",
     "external-editor": "^3.1.0",
     "magicast": "^0.5.3",
     "semver": "^7.8.5",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@clerk/shared": "^4.29.1",

packages/cli-core/src/cli-program.ts

@@ -24,6 +24,7 @@ import { registerCompletion } from "./commands/completion/index.ts";
 import { registerUpdate } from "./commands/update/index.ts";
 import { registerDeploy } from "./commands/deploy/index.ts";
 import { registerWebhooks } from "./commands/webhooks/index.ts";
+import { registerMigrate } from "./commands/migrate/index.ts";
 import { getEnvironment } from "./lib/config.ts";
 import {
   setCurrentEnv,
@@ -83,6 +84,7 @@ const registrants: CommandRegistrant[] = [
   registerUpdate,
   registerDeploy,
   registerWebhooks,
+  registerMigrate,
   registerExtras,
 ];