Skip to main content

Move your users to Clerk from the platform you use today, and keep their passwords when your platform exports them. The Clerk CLI exports your users, checks each one against your Clerk instance before it writes anything, and imports them. If something goes wrong, it can undo the import.

Supported platforms

Better Auth, Firebase, and Supabase exports keep password hashes, so most of those users sign in with the passwords they already have. Auth0 releases hashes only through a support request. Auth.js and WorkOS users, and users copied with clerk migrate export clerk, reset their password or sign in another way. Each guide lists the exceptions.

Choose an approach

Most migrations import every user at once, which is what clerk migrate does. A trickle migration moves them over time while both systems run, and you build that import yourself with the Backend API. Plan your migration covers the trade-offs of each, and how your app keeps referencing users by the IDs they had before.

Requirements

Install the Clerk CLI, sign in, and link the project directory you'll run the migration from to the Clerk application you're importing into:

terminal
npm install -g clerk
clerk auth login
clerk link

To skip clerk auth login and clerk link, set CLERK_SECRET_KEY to the of the instance you're importing into, or pass it with --secret-key.

To skip the global install, replace clerk with npx clerk@latest in each command. To update an existing install, run clerk update.

import and undo target the linked application's development instance by default. Pass --instance prod or a full instance ID to choose another. With a Secret Key, the key picks the instance, so pass the production instance's key to import into production. For other ways to pick the instance and Secret Key, see choose the destination instance.

The CLI stores each run in .clerk/migrate/<run_id>/ and adds .clerk/ to .gitignore. To store runs elsewhere, see command behavior.

Warning

New development instances have a limit of 100 users. Production instances have no user limit. Before creating users, the import checks a development instance's count against its limit and rejects the users past it. To rehearse with a larger export, import into development with --allow-partial, check the result, undo the run, then import everyone into production. See instance user limits for the commands, overrides, and fallback behavior.

Run your migration

If you work with an AI coding agent, the clerk-migrate skill can run your migration for you with the Clerk CLI. Install Clerk's skills:

terminal
npx skills add clerk/skills

Then ask your agent to migrate your users to Clerk. The skill exports your users, runs a dry run against your instance, and shows you what it found. It imports only after you approve.

To run the migration yourself, export your users, check them against your instance, then import them:

terminal
clerk migrate export <platform>                # prints a run ID
clerk migrate import <export_run_id> --dry-run # checks, writes nothing
clerk migrate import <export_run_id> --yes     # imports

If you exported your users another way, skip clerk migrate export and pass the file to clerk migrate import with --source.

Each platform's guide walks through these steps and lists what comes across and what doesn't, such as social sign-ins. For the checks, re-runs, undo, and exit codes, see How the CLI migrates users. Run clerk migrate <command> --help to see all options.

Foreign keys

Keep referencing your users by the IDs they had before the migration.

How the CLI migrates users

Learn how the CLI checks users, continues an interrupted import, and undoes one.

Account linking

Learn how Clerk links a social sign-in to an imported user.

Feedback

What did you think of this content?

Last updated on