Index of every page on this site: llms.txt
All skills
clerk avatar

/clerk-migrate

@95f241a official
by clerkclerk/skills95 stars
6
Run it yourself

Migrate users into Clerk from another auth provider, or between Clerk instances, using the `clerk migrate` command family. Use when the user says "migrate my users to Clerk", "import users from Auth0 / Supabase / Firebase / Auth.js / Better Auth / WorkOS", "export my users", "move users from development to production", "undo the import", or hands over a user export file (JSON or CSV) and asks what to do with it. Covers exporting from the auth platform, choosing a source, writing one for a platform with no built-in, checking and running the import, inspecting runs, and undoing one. Don't use for adding Clerk to an app (use clerk-setup) or for general CLI tasks (use clerk-cli).

Use this Skill: https://skilld.dev/gh/clerk/skills/clerk-migrate

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesexport.md

≈4.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Exporting users

clerk migrate export <platform> pulls users out of an auth platform into a new run. clerk migrate import <export-run-id> reads that run with no --source, because the export file names its own source.

clerk migrate export                    # picker, human terminals only
clerk migrate export supabase --db-url "postgres://…"

In agent mode the bare picker is a usage error that lists the platforms. Always pass one.

Where the file goes

Every export is a run. The file lands in the run folder, <project root>/.clerk/migrate/<run-id>/export.json, and the CLI asks nothing about where it goes. -o, --output <path> writes it somewhere else instead, resolved against the current directory; the run still records where. The path must end in .json.

The file is an envelope around the users:

{
  "clerkMigrate": 1,
  "source": "supabase",
  "exportedAt": "2026-09-29T14:15:02.000Z",
  "runId": "20260929-141502-a1b2",
  "users": [ … ]
}

A Firebase export adds firebase, the project's hash parameters, when it could read them. The export prints the run ID and the import command:

Exported 3 users to /project/.clerk/migrate/20260929-141502-a1b2/export.json
Run 20260929-141502-a1b2. See each user with `clerk migrate runs 20260929-141502-a1b2`.

Import them with:
  clerk migrate import 20260929-141502-a1b2

--json prints { target, run, output, users, skipped, coverage, next } on stdout, plus sections and truncated when they apply, and never prompts. A missing credential then exits 2 naming the flag to pass.

The default .clerk/ folder is gitignored automatically; a -o, --runs-dir or CLERK_MIGRATE_DIR path is not. The export file holds user data (and, for Firebase, the signer key), so keep it out of chat output and commits.

What each platform needs

Platform Credentials Environment variables Passwords
clerk Resolved by the CLI, or --secret-key / --app / --instance CLERK_SECRET_KEY Not exportable
auth0 --domain, --client-id, --client-secret AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET Not exportable
workos --api-key (the sk_… secret key) WORKOS_API_KEY Not exportable
supabase --db-url (Postgres only) SUPABASE_DB_URL bcrypt or argon2, per user
authjs --db-url AUTHJS_DB_URL none — Auth.js stores none
betterauth --db-url BETTERAUTH_DB_URL scrypt, bcrypt or argon2, per user
firebase --service-account <path> none scrypt digests + four parameters

Resolution is flag → environment variable → a prompt, masked for secrets. Firebase has no environment variable, and clerk uses a picker (see Clerk). The CLI does not read .env files for these platform credentials. In agent mode there is no prompt, so pass the flags; a missing credential exits naming every missing one at once. Ask the user for a credential; never guess one, and never write it into a .env file on their behalf.

A rejected credential is asked for again — for humans only. A connection string, Firebase key, set of Auth0 credentials or WorkOS key that the far end rejects re-prompts in an interactive run, and the rest of the export continues. Agent mode, a non-TTY, --json and -y fail outright instead. If an export fails on a credential, relay the error and ask the user for a corrected value.

Reading the field coverage report

An export that found users prints a coverage table before its final lines:

Field coverage
  ✓ 1247/1247 have an email address
  ! 89/1247 have a phone number
  ! 1102/1247 have a password (not exportable — see below)

✓ means every user has the field, ! some, ✗ none. Tell the user about the ! and ✗ rows. A user with a password the export cannot carry resets it after the import.

Three platforms never export passwords, Clerk, Auth0 and WorkOS, and each shows it differently:

  • Clerk counts the users who have a password (password_enabled), labelled "not exportable", and warns when any user has one.
  • Auth0 has no password row. It warns on every export that found users.
  • WorkOS always shows ✗ 0/N have a password (WorkOS returns none), and warns on every export that found users.

Clerk

clerk migrate export clerk --app app_source123 --instance dev

Pages the whole instance 500 users at a time. Password digests, TOTP secrets and backup codes are never returned by the API — only the *_enabled booleans. Users who signed in with a password reset it on the destination.

Name the source instance. --secret-key, --app, --instance or an exported CLERK_SECRET_KEY are taken as-is. Without one, a human gets a picker of every instance on their account, and an agent, --json or -y run exits 2, because what the CLI resolves on its own is usually the linked project, which is usually the migration's destination.

The import sets each user's external_id to their old Clerk user ID, so an app's own external_id moves to private_metadata.clerkExternalId. The export warns about it: tell the user anything that looks users up by external_id needs updating. If the user a page continues from is deleted mid-export, the export fails; run it again.

When the users are in a different Clerk application, ask the user for that application's secret key and pass it with --secret-key. The key names the instance on its own, so you need no app or instance ID.

For the full dev → production flow, see clerk-to-clerk.md.

Auth0

clerk migrate export auth0 --domain my-tenant.us.auth0.com --client-id … --client-secret …

Needs a machine-to-machine application with the read:users scope: Auth0 Dashboard → Applications → APIs → Auth0 Management API → Machine to Machine Applications. --domain is the tenant's own *.auth0.com host, not a custom domain.

Two limits to state up front:

  • No password hashes. The Management API does not return them; Auth0 releases them only through a support request. Either add a passwordHash field to each user before importing, or migrate without passwords.
  • 1000 users maximum. Auth0 pages this endpoint only through the first 1000. Past that the export stops, exits 1 with the file holding what came back, and sets truncated: true under --json. Use Auth0's bulk export job instead. Do not present a truncated export as the whole tenant.

WorkOS

clerk migrate export workos --api-key sk_…
clerk migrate export workos --api-key sk_… --with-identities

Needs the secret API key — the one starting sk_, from the WorkOS dashboard under API Keys. WorkOS is API-only, so there is no --db-url option. Pagination is cursor-based, so unlike Auth0 there is no user ceiling.

  • No passwords, no TOTP. WorkOS accepts password hashes on import and never returns them, and returns TOTP secrets only at enrolment. Unlike Auth0, no support request gets them. Every password user resets or signs in through SSO.
  • --with-identities is off by default, and it is not free. WorkOS has no bulk endpoint for OAuth identities, so it is one extra request per user — 1,000 users means roughly 1,010 requests. Nothing it returns can be imported; it buys an OAuth providers block under the coverage table and an identities array in the export file. Useful for deciding which social connections to enable in Clerk. Ask before passing it on a large tenant. A human run asks once, defaulting to no; -y skips it unless --with-identities is passed.
OAuth providers
  GoogleOAuth        2 users
  MicrosoftOAuth     1 user
  no OAuth provider  2 users
  not readable       1 user

not readable is a lookup that failed, not a user with no providers — report it as such. Provider counts can sum past the user count, since one user can hold two.

Non-interactive runs print progress to stderr every 10 pages and, with --with-identities, every 500 users — a long silence is not a hang.

Supabase

clerk migrate export supabase --db-url "postgres://postgres:…@db.xxx.supabase.co:5432/postgres"

Reads the auth.users table directly rather than going through the Admin API, because encrypted_password exists only in the database. That is what lets password digests come across, so users keep their passwords. The source detects bcrypt or argon2 per user and drops anything else with passwordDropped.

Find the connection string in the Supabase dashboard under Connect:

  • Direct: postgresql://postgres:[PASSWORD]@db.[REF].supabase.co:5432/postgres — needs the IPv4 add-on.
  • Session pooler: postgres://postgres.[REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres. Works without the add-on, and is the better default. The CLI's hint names it too.

The export keeps raw_app_meta_data. The import's checks read it for each user's providers, and reject users whose only provider is not enabled in Clerk, unless they can sign in by email code, email link or phone code instead.

The source skips deleted users (deleted_at set) and anonymous users. The dry run lists them as skipped, and the import goes ahead without them. A banned_until in the future imports as banned, and phones stored as bare digits get a +.

Auth.js (NextAuth)

clerk migrate export authjs --db-url "mysql://user:…@127.0.0.1:3306/authjs"

Postgres, MySQL, SQLite and libsql/Turso all work. Auth.js has no single schema — Prisma capitalizes the table, Drizzle does not — so the export tries next_auth.users on Postgres (for @auth/supabase-adapter), then User, user and users, and reports which it found.

Auth.js core stores no passwords. Those users arrive with no credentials and will sign in through their OAuth provider or a fresh Clerk flow. An app that also uses the Credentials provider stores passwords wherever it chose, which the export does not read, even a password column on the user table. Migrate those separately, or have those users reset their password.

The export also reads the account table (Account, account, accounts or next_auth.accounts) for each user's OAuth providers, and keeps them as providers. The import's checks count them and offer to turn on any provider Clerk has off.

Auth.js leaves an OAuth user's email unverified (emailVerified: null; only an email-link sign-up gets a date). Imported as is, that user is rejected by an instance that requires an email. On one that doesn't, Clerk won't link their social sign-in to the unverified address, and it creates a second user. The export counts these users and warns. --trust-oauth-emails marks them verified, dated at the export. Ask the user before passing it, and recommend it only when every provider the app uses verifies addresses: a provider that never verified one lets whoever holds the address claim the account. Without an account table, the export can't tell who signs in with OAuth.

Better Auth

clerk migrate export betterauth --db-url "./db.sqlite"
clerk migrate export betterauth --db-url "libsql://app-org.turso.io?authToken=…"   # or set TURSO_AUTH_TOKEN

Plugin columns are detected from the live schema rather than assumed, because selecting a column that is not there fails the whole query. Username, admin (banned), phone-number and the rest come across when the plugin is installed. A ban carries only while banExpires is unset or in the future. Anonymous-plugin users are skipped. The dry run lists them, and the import goes ahead without them.

Passwords come from a LEFT JOIN onto the credential account row — left, so a user who only ever signed in with OAuth is still exported. The import detects the hasher per user: Better Auth's own scrypt, bcrypt and argon2 come across, and any other hash is dropped. A user with two credential rows whose hashes differ is exported without a password. See sources.md for the NFKC caveat.

Connection strings (supabase, authjs, betterauth)

--db-url accepts postgres:// or postgresql://, mysql:// or mysql2://, libsql:// (Turso), and a SQLite file: file:…, or a path starting with ./ or ending in .db, .sqlite or .sqlite3. supabase takes Postgres only. A libsql token comes from ?authToken= on the URL, or from TURSO_AUTH_TOKEN / LIBSQL_AUTH_TOKEN. A password pasted in raw with @, # or / in it is percent-encoded for you when the string would not otherwise parse; an already-encoded one is left alone.

Connection strings are redacted in every message the CLI prints (postgres://***@host/db), including when the password itself contains an unencoded @. Keep them out of your own output too.

Firebase

clerk migrate export firebase --service-account ./service-account.json

Needs a service account key with the Firebase Authentication Admin role (or Viewer plus the firebaseauth.configs.getHashConfig permission): Firebase console → Project settings → Service accounts → Generate new private key. --service-account takes the key file's path. Without it, a human is prompted — the answer can be a path or the key's JSON pasted whole, so a key kept in a password manager never has to touch disk. Agent mode names the flag instead. When the user pastes the key's JSON, run mktemp to create an empty file outside the project that only the user can read. Write the JSON into that file with your file-write tool, run chmod 600 <file>, pass its path, and rm the file after the export, whether or not it succeeded. Don't put the key in any shell command: --service-account '<json>', printf, echo and a heredoc all place it on a command line that shows up in ps. Write into the file mktemp made, not a new one. The chmod restores owner-only access if your tool replaced the file instead of writing into it. Never save the key inside the project. The key is validated before any network call, so a web app config downloaded by mistake fails at once, naming the field it lacks ("project_id" is missing).

Firebase's scrypt is a modified variant. A digest is worthless without the project's four hash parameters. The export reads them from the project and saves them in the envelope, so the import needs no --firebase-* flags:

clerk migrate import <export-run-id> --dry-run

A file from firebase auth:export has no envelope. Import it with --source firebase and the four parameters. For an agent, prefer the environment variables, which keep the signer key out of the command line: CLERK_FIREBASE_SIGNER_KEY, CLERK_FIREBASE_SALT_SEPARATOR, CLERK_FIREBASE_ROUNDS and CLERK_FIREBASE_MEM_COST. Ask the user to export them in their shell. They fill in only when the file has no parameters. The flags work too:

clerk migrate import users.json --source firebase --dry-run \
  --firebase-signer-key "…" --firebase-salt-separator "…" \
  --firebase-rounds 8 --firebase-mem-cost 14

The four parameters are required as a set. A partial set produces a well-formed digest that verifies against nothing, so users import and then cannot sign in. Each is range-checked: keys must be base64, rounds and memory cost 1 to 16. Flags override the envelope, so a rotated key needs no re-export. A human import with no parameters is prompted for them. A continued run with different parameters exits 2. An export with no password hashes needs no parameters.

Reading the config needs a broader role than listing users. If it is denied, the export still succeeds, names the missing firebaseauth.configs.getHashConfig permission, and points at Authentication → Users → (⋮) → Password hash parameters. Ask the user to copy the four values from there and pass them as the --firebase-* flags on the import.

The export also warns about users whose hashes Firebase redacted (only a re-export with the right role recovers them) and about users uploaded with bcrypt or HMAC, whose hashes Firebase does not return.

FIREBASE_AUTH_EMULATOR_HOST is honoured, so this works against the local emulator too.

Troubleshooting

Symptom Cause and fix
"Connection closed" on a database export Unreachable host or a closed port. On Supabase, switch to the Session pooler string or enable the IPv4 add-on.
Credentials rejected Check the user and password. The CLI encodes @, # or / only when the string wouldn't parse otherwise; if it still fails, URL-encode the password.
Table does not exist Supabase: enable Auth and connect as postgres. Better Auth: run npx @better-auth/cli migrate. Auth.js: run the ORM's migrations.
Auth0 401 / 403 Wrong domain, client ID or secret, or the M2M application lacks the read:users scope.
WorkOS key rejected Use the secret API key starting sk_, from the right WorkOS environment.
Firebase "Google rejected the service account" Wrong or stale service account key. Download a fresh one for the right project.
Export succeeded but almost every field is empty Wrong table or wrong platform. Check the coverage report before importing, not after.

Next step

Follow the import flow in SKILL.md: dry-run the printed run ID, relay the checks, and get the user's yes before importing with --yes.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings3d3 checks · Risk MEDIUM
  • Gen Agent Trust Hub3d

    The skill facilitates user migrations to Clerk. It includes features for generating custom transformation scripts and analyzing user data files, which present potential security surfaces. It follows strong security practices for credential handling and user consent.

  • Socket3d

    No alerts

  • Snyk3d

    Risk: MEDIUM · 1 issue

Signed by skilld at 95f241a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago
What it can do
Runs commands Reads files Edits files
metadata
{
  "author": "clerk",
  "version": "1.0.0"
}
All 5 allowed tools
BashReadWriteGrepGlob
Other metadata
compatibility
Requires the `clerk` CLI binary 4.2.0 or later (npm package `clerk`, or `bunx clerk@latest`), the first release with the `clerk migrate` command family. Needs a Clerk session from `clerk auth login`, or a Backend API secret key passed with `--secret-key`. No other dependency: do not install an SDK or a database driver.

README badge

README badge for clerk/skills/clerk-migrate