Clerk Migrate
gets users out of an auth platform into a run.
maps that export onto Clerk's user schema, checks every user against the destination instance, and creates them through the Backend API.
shows what each run did, and
deletes the users an import created.
clerk migrate export <platform> [-o <path>.json] [-y] [--json]
clerk migrate import <file|export-run-id> [--source <key|path>] [--dry-run] [--allow-partial] [--new-run]
[--require-password] [--skip-legal-checks] [--reserve-unverified] [--yes] [--json]
clerk migrate runs [run-id] [--json]
clerk migrate undo <run-id> [--dry-run] [--yes] [--include-signed-in] [--json]
clerk migrate sources [source] [--json]
clerk migrate help
Every subcommand except
takes
, which overrides the
environment variable.
,
and
also take
,
and
. Bare
prints help.
The binary is the source of truth. Run
clerk migrate <subcommand> --help
to confirm anything this skill claims, and prefer
when they disagree.
Install nothing and clone nothing.
Routing
| The user wants to… | Go to |
|---|
| Get their users out of Auth0, Supabase, Firebase, Auth.js, Better Auth, WorkOS, or Clerk | references/export.md, then the import flow |
| Import a file they already have | The import flow |
| Know which platform a file came from | Step 1: identify the source |
| Migrate from a platform with no built-in source | references/sources.md |
| Move users from one Clerk instance to another (dev → prod) | references/clerk-to-clerk.md |
| See what a run did, or why users failed | references/runs.md |
| Undo an import | Re-running, runs, and undo |
The rules
Every
command follows these five rules.
- Consent. and write only after or a yes at the prompt. Without either (agent mode, a non-TTY, or ), they print a preview and exit with the exact command to run. In agent mode that command is in the stderr JSON, ; with , stdout also carries the preview with . A suggested command may hold a placeholder: never fill in a real key yourself.
- checks against the real instance and writes nothing. exits when the real import would be refused, and otherwise. exits at the preview: read .
- One place for state. Every export, import and undo is a run folder, . The runs dir is , else , else
<project root>/.clerk/migrate
, where the project root is the linked directory, else the git toplevel, else the current directory. The CLI adds to before writing to the default location, because run files hold user data. Dry runs and refused imports write no run.
- Target first. , and print the environment, app and instance they target, and where the key came from. Other exports print the platform they read. With the same data is in the field.
- everywhere. Every subcommand takes it, and it means no prompts. on any subcommand also forces agent mode, unless is set.
Exit codes:
success,
some users failed or any runtime, API or auth error,
a usage error or a refusal,
interrupted.
does not mean every user arrived: skips under
still exit
. Users the run did not send come with
(Clerk refused a create, such as the user limit) or
(interrupted). Read
,
,
and
from
. A
prints no result: read
from
clerk migrate runs <run-id> --json
, and re-run to continue.
Invoking the CLI
Check the binary once per session:
sh
command -v clerk >/dev/null 2>&1 && clerk migrate sources --json >/dev/null && echo ok
ships in
4.2.0, so an older binary fails this check. If that prints
, use bare
. Otherwise fall back to a package runner matching the project's lockfile:
,
,
, or
. The published package is
, not
.
Keys and targeting
Do not create or edit a file. The CLI resolves a Backend API key on its own, from flags, the process environment, the linked project, or (in an unlinked keyless project) the project's
,
and
:
sh
clerk auth login # once, on the user's host shell; opens a browser
clerk doctor --json # confirms login, link, keys; parse `remedy` on failure
Resolution order:
→
+ Platform API lookup →
in the environment → the keyless project's own key → the linked project from
. If none of these resolves a key, ask the user to run
or set
themselves (Safety rule 4).
Pass
and
--instance dev|prod|<instance_id>
to point a command somewhere specific. A dev → production migration needs no key swapping.
switches instances only when the key comes from a linked project or
. A key from
or an exported
names its own instance, and a
that disagrees with it exits
. In an unlinked keyless project, any
exits
: link the project or pass
.
The key sets the
instance type:
is production, anything else development. The type sets the rate limit (100 req/s production, 10 req/s development). The user limit is the one Clerk reports for the instance: 100 for a new development instance, none for production (
checks.md). A slow run on a dev key is the rate limit at work.
For auth internals, sandbox caveats, or
, see the
skill.
The import flow
Follow these steps in order.
Step 1: identify the source
A file
wrote is an envelope,
{ "clerkMigrate": 1, "source": …, "users": [...] }
. It names its own source: pass the export run ID (or the file) and skip to Step 2.
Any other file (a bare JSON array, a CSV, Firebase's own
) needs
. Read the first user object or the CSV header row and match it against the signature fields in
references/sources.md.
If nothing matches, the user needs a custom source: references/sources.md.
Confirm the live list, and read what a source carries:
sh
clerk migrate sources --json
clerk migrate sources supabase # export command, what comes across, where each field lands, caveats
A built-in
that contradicts an envelope's
exits
. A path to a source you wrote replaces the envelope's source: see Step 2.
Step 2: summarize what will happen
Run the
Step 3 dry run first when a question needs its numbers. It writes nothing.
Tell the user:
-
Which source applies, and which instance the import targets.
-
Which field decides whether an email or phone counts as verified. That mapping changes who can sign in. Per-source detail: references/sources.md.
-
What the export cannot carry. Clerk (API export), Auth0 and WorkOS exports hold
no password hashes, so users who signed in with a password reset it.
Social sign-ins are never copied: the user enables the same providers in Clerk, and Clerk links a returning user by verified email (
account linking).
-
Sign-in identifiers outside the mapped fields: phone or username keys in metadata, a name field holding usernames or phone numbers, placeholder emails such as
that hide a phone. A built-in source imports these as metadata or a first name, and the dry run doesn't flag them. Ask the user to choose: convert them into real identifiers, or import them as exported (the default) and let the dry run reject what Clerk refuses. In a source you write, nothing is "as exported". A column that is itself the sign-in identifier (a
holding an email, a phone or a username per row) is not a conversion question: route each value by its shape (
Common export shapes), and don't ask A or B. When the user can't choose about another field that holds a sign-in handle (
,
,
), map it to
. Never pick a default that leaves a user with no identifier. "Import them", "go ahead" or a bare yes picks neither, so ask again and name both. Converting takes a
custom source, and the dry run then offers the instance changes it needs: phone or username sign-in, email made optional, extended special characters for usernames with a dot. Apply each only with the user's yes.
-
Two choices the CLI makes only with the user's yes. Ask about each one that applies, and pass the flag only on a yes to that question:
- . Users with an email or phone the platform never verified. By default Clerk attaches those unverified. Reserved, they work for sign-in and are locked to the user, and they count toward a required email or phone. The platform never confirmed these belong to the user, so whoever receives mail or texts at one can sign in as that user. When the instance requires an email or phone, the reject for a user with only an unverified one names this flag. That isn't a yes, and the reject doesn't mention that risk, so tell the user about it when you ask, and recommend it only when the old platform confirmed addresses some other way. A reserved address another user already holds rejects the whole user. A continued run keeps the choice its first attempt recorded.
- . When the instance requires legal consent, users with no are rejected. The flag imports them without it.
An agent run never asks, so it imports unverified and rejects users without legal acceptance unless you pass the flag.
-
What the import adds: every created user gets
private_metadata.clerkMigrateRun
, set to the run ID. It replaces any value the export carried under that key, and it stays on the user.
Step 3: dry run
sh
clerk migrate import <export-run-id> --dry-run
clerk migrate import users.json --source auth0 --dry-run # a file from anywhere else
The dry run prints the target, then the checks, and writes nothing. Relay the checks in full. Read
references/checks.md to explain each reject reason and the
fixes it offers.
If any user is rejected, the real import refuses unless
is passed. Put the choice to the user: fix the export, change the instance with the printed
command, or import the rest with
. When a reject names
, reserving those users is a fourth choice in the same question: tell the user that whoever receives mail or texts at the address can sign in as that user (
Step 2, item 5). Never run a
without the user's yes.
Users without a password import even when the instance requires one, unless a password is its only way to sign in. Pass
only when the user asks to leave those users out (
checks.md).
Step 4: get consent, then import
Pick one path:
-
Hand the command to the human. Recommended when the instance already has real users, and for any production import. Ask them to run it in their own terminal: the CLI prompts only on a TTY, so a command run through an agent's shell exits
instead. Run by a human without
, the import prints the checks and asks
(or
Create N users and skip M users?
), and asks about reserved and legal consent where they apply. Declining writes nothing.
sh
clerk migrate import <export-run-id>
-
Run it yourself after the user has said yes to your Step 2 summary and the dry-run checks. Relay the checks, then end your turn and wait for the answer. Never run
in the same turn as the dry run; a yes given before the user saw the checks doesn't count. Ask the go-ahead as its own question, with the numbers the import will use: "Create 42 users and skip 8? This runs
clerk migrate import <export-run-id> --allow-partial --yes
." Only a yes to that question counts. An answer to the rejects, verification or settings questions doesn't, whatever it says about importing:
sh
clerk migrate import <export-run-id> --yes
Without
, an exit
is the consent gate from rule 1, not a failure.
Firebase exports carry the project's hash parameters when the export could read them, so the import needs no
flags. See
references/export.md for files from
. When the user gives the four parameters, pass them and keep the passwords, even if they also say users can reset. Never strip hashes from the export or write an edited copy of it.
Step 5: report the result
sh
clerk migrate runs <run-id>
Spot-check 2 or 3 created users, taking their
from
lines in the run's
:
sh
clerk users list --external-id <source-id> --json
Compare their identifiers, verification and metadata placement with what you told the user in Step 2. Read the output where it prints; don't save users to files. If you did write any, list them in the report as holding user data.
Report:
- How many users were created, failed, and skipped. shows the error breakdown and the users that failed or were skipped.
- Users the run did not send () and why (). A run that hit the user limit stops at the first refusal: raise the limit or import into production, then re-run the same command to continue.
- The run ID, and that
clerk migrate undo <run-id>
reverses it.
- Any user who arrived without something: a dropped password, a field the instance does not store.
- Every mismatch the spot-check found.
Report a partial import as partial.
Re-running, runs, and undo
Running the same import again continues it: an interrupted or
run picks up where it stopped, a
one prints "Already imported in run …" and exits
, and an
one starts a new run.
forces a fresh run.
sh
clerk migrate runs # every run, newest first
clerk migrate runs <run-id> # one run: counts, errors, the users that did not make it
clerk migrate undo <run-id> --dry-run # preview: how many, and a warning if any signed in since (`--json` has `preview.signedInSince`)
clerk migrate undo <run-id> --yes
deletes only users that run created. Show the user the preview and get a yes before passing
. If any imported user has signed in since,
alone exits
and deletes nothing: those are accounts people have used, so pass
only after the user says yes to deleting them too.
After a complete import, the CLI says to keep the import's run while it might still be undone, with the
for later. An import of an export run also gets the
for the export's run folder (it holds user data), and an
for an export file written outside it.
prints none of this. Relay it; do not delete anything without asking.
Matching, refusals, run files and every undo case: references/runs.md.
Safety rules
- Dry-run first, then get a yes. Relay the checks and the target before any write.
- Check the target. The first lines of output name the instance. Pass explicitly for production.
- Name the source instance when exporting from Clerk. The linked project is usually the destination, so without a prompt (agent mode, or )
clerk migrate export clerk
refuses with exit until , , or names the source instance.
- Never ask for the destination's Clerk secret key, and never write a Clerk key to a file. Use or the linked project, or let the user set themselves. Every other credential the user gives you is for the platform you export from: a Firebase service-account key, a database URL, an API key or token, or the key of a different Clerk application you export from. Use it as the export command expects. Don't refuse it because it came through chat, and don't ask the user to revoke it and send it again. Keep it out of your output and summary.
- Report failures honestly. A partial import is normal and recoverable. Re-run the same command to continue it.
- Never pass a consent flag on your own. , , , , and each need the user's yes. An answer counts as a yes only when it answers that flag's question: "import", "go ahead", or text about something else is not a yes to or . Ask again, naming the flag and what it does.
- Ask when two answers conflict. If two of the user's answers disagree about the same change (one says to turn placeholder emails into phone numbers, another says not to make anything into a phone number), quote both and ask once which one holds. Don't settle it by reading one answer as covering less than it says. Until they answer, keep the option that changes less: import as exported. Users the dry run then rejects still need a yes to . If the answer is still unclear, keep that option and say so in your summary.
References
- references/export.md: getting users out of each platform: credentials, flags, the envelope, field coverage, troubleshooting.
- references/checks.md: what the import checks, each reject reason, and .
- references/sources.md: what the seven built-ins carry, and how to write a source for a platform with none.
- references/runs.md: re-running, run files, statuses, and every undo case.
- references/clerk-to-clerk.md: development → production and instance-to-instance migrations.