# Migrate between Clerk instances

Use two [Clerk CLI](https://clerk.com/docs/cli.md) commands to move users between instances, such as from development to production or between applications. Each command names its own target, so you never swap a Secret Key between steps.

> Clerk's API never returns password digests, time-based one-time password (TOTP) secrets, or backup codes, so `clerk migrate export clerk` can't copy them, and the users you migrate will have to reset their password in the destination. The CLI exports identifiers, names, metadata, and original signup dates. To keep passwords, [import a Clerk Dashboard export](#keep-passwords-with-a-clerk-dashboard-export) instead.

## Migrate with an AI agent

If you work with an AI coding agent, the [`clerk-migrate` skill](https://clerk.com/docs/guides/ai/skills.md) can run your migration for you with the Clerk CLI. Install Clerk's skills:

filename: terminal
```sh
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.

## What you need

Install the [Clerk CLI](https://clerk.com/docs/cli.md), sign in, and link the project directory you'll run the migration from to the Clerk application you're importing into:

filename: terminal
```sh
npm install -g clerk
clerk auth login
clerk link
```

To skip `clerk auth login` and `clerk link`, set `CLERK_SECRET_KEY` to the Secret Key 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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#command-behavior).

> New development instances have a [limit of 100 users](https://clerk.com/docs/guides/development/managing-environments.md). 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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#instance-user-limits) for the commands, overrides, and fallback behavior.

Your CLI login, or the Secret Keys you pass, needs access to both instances. If they're two instances of one linked application, `--instance dev` and `--instance prod` are enough. If they're separate applications, target each with its own `--app <application_id> --instance <instance>` or `--secret-key <secret_key>`.

## What migrates

- **Passwords and TOTP secrets, from a Dashboard export:** Importing a Clerk Dashboard export keeps them. `clerk migrate export clerk` can't export them, so users you migrate that way must reset their password in the destination instance. Plan how you'll tell them before you cut over.
- **Verified primary identifiers:** The CLI exports verified and unverified emails and phones in separate fields, primary first. The import attaches them in that order. Clerk puts the first entry on the user and attaches the rest afterward, so the order decides which address a user signs in with. If the primary isn't verified, the CLI exports it as unverified, and the first verified address becomes primary instead. By default, unverified addresses stay unverified. The checks reject a user whose only email is unverified when the destination requires an email. To reserve those unverified addresses instead, see [unverified emails and phones](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#unverified-emails-and-phones).
- **Signup dates, from either export:** The import copies `created_at`. The CLI's API export also includes `legal_accepted_at`; the Dashboard CSV doesn't.
- **Metadata, from the CLI's API export:** `publicMetadata`, `privateMetadata`, and `unsafeMetadata` keep their trust levels. The Dashboard CSV doesn't include metadata.
- **Account state, from the CLI's API export:** The import copies `banned`, `createOrganizationEnabled`, `createOrganizationsLimit`, and `deleteSelfEnabled`. The Dashboard CSV doesn't include these fields.
- **Clerk user IDs:** Each user's ID in the source instance becomes `external_id`. The destination instance mints new `user_` IDs. If your app stores the old ones, read the original through a session token claim. See [foreign keys](https://clerk.com/docs/guides/development/migrating/plan-your-migration.md#foreign-keys). With the CLI's API export, an existing `external_id` moves to `privateMetadata` as `clerkExternalId`.

## What doesn't migrate

- **Backup codes and other account data:** Neither export includes backup codes. The import omits Organizations, sessions, social accounts, passkeys, Web3 wallets, and profile images.

1. ## Export from the source instance

   Run the export, naming the source instance:

   filename: terminal

   ```sh
   clerk migrate export clerk --instance dev
   ```

   If you pass `--secret-key` and `--instance` together, the instance has to match the key's, or the export refuses to run.

   Always name the source instance. Your linked project is usually where the users are _going_, so the export won't default to it as the source instance. If you don't pass `--instance`, `--app`, `--secret-key`, or an exported `CLERK_SECRET_KEY`, the CLI lists every instance on your account and asks you to pick one. The linked application's instances come last, marked as the likely destination. Listing instances needs `clerk auth login`. Without it, the CLI offers only the instance it resolved, and asks you to confirm it. The CLI can't ask an AI agent, so in agent mode, or with `--yes` or `--json`, the export refuses to run until you name the source instance.

   The export saves your users as `export.json` in a new run, and prints the run ID and a field coverage table:

   ```text
   Field coverage
     ✓ 87/87 have an email address
     ✗ 0/87 have a phone number
     ! 12/87 have a username
     ! 60/87 have a first name
     ! 58/87 have a last name
     ! 74/87 have a password (not exportable — see below)
   ```

   Pass `-o <path>` to write the file somewhere else. The path has to end in `.json`.

   The last row counts users who _have_ a password in the source instance. None of those digests are in the file, because the API doesn't return them.
2. ## Import into the destination instance

   Check the export against the destination first. A dry run writes nothing and skips the import's consent, legal acceptance, and reservation questions, so add `--skip-legal-checks` to preview importing users without [legal acceptance](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#legal-acceptance), or `--reserve-unverified` to preview reserving [unverified emails and phones](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#unverified-emails-and-phones):

   filename: terminal

   ```sh
   clerk migrate import <export_run_id> --instance prod --dry-run
   ```

   Name the destination: the import refuses to write into the instance the export came from. The export recorded its source, so the import needs no `--source`.

   If the checks reject a user, fix the file or instance, or pass `--allow-partial` to import the users that pass. See [check before you import](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#check-before-you-import).

   After the checks pass, rerun the same command with `--yes` instead of `--dry-run`, keeping `--instance prod` and other flags. Leave off `--yes` to confirm at a prompt. Use the import run's ID to check its results or undo it. To [continue an interrupted import](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#continue-an-interrupted-import), run the same command again.

   If you're going the other way, copying production into development for staging, the checks reject every user past the development instance's user limit. Pass `--allow-partial` to import up to it. The users past the limit aren't created, and the import records them as `skipped`.
3. ### Keep passwords with a Clerk Dashboard export

   A [user export from the Clerk Dashboard](https://clerk.com/docs/guides/development/migrating/export-from-clerk.md#export-from-the-clerk-dashboard) includes each user's password digest, password hasher, and TOTP secret. The `clerk` source reads that CSV, so importing it keeps your users' passwords:

   filename: terminal

   ```sh
   clerk migrate import <path_to_csv> --source clerk --instance prod --dry-run
   ```

   A file the Dashboard wrote doesn't name its source, so it needs `--source clerk`. When the checks pass, run the same command with `--yes` instead of `--dry-run`.
4. ## Verify the migration

   1. Read what the run did. It lists the users that failed or were skipped, and why:

      filename: terminal

      ```sh
      clerk migrate runs <import_run_id>
      ```

   2. Confirm the users exist in Clerk:

      filename: terminal

      ```sh
      clerk users list --instance prod
      ```

   3. Sign in to the destination as a migrated user. If their password wasn't migrated, test the password reset flow and confirm that the reset email reaches the imported address.

## Undo the migration

Preview the users the import created, using the import run's ID:

filename: terminal
```sh
clerk migrate undo <import_run_id> --dry-run
```

Then delete them:

filename: terminal
```sh
clerk migrate undo <import_run_id> --yes
```

`--yes` doesn't delete users who have signed in since the import. Add `--include-signed-in` to authorize those deletions too. Confirming at the interactive prompt also authorizes them.

Pass the same `--instance`, `--app`, or `--secret-key` you gave the import. See [undo an import](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#undo-an-import) for confirmation rules, refusal conditions, and retries.

## Next steps

- [Foreign keys](https://clerk.com/docs/guides/development/migrating/plan-your-migration.md#foreign-keys): Keep referencing your users by the IDs they had before the migration.
- [How the CLI migrates users](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md): Learn how the CLI checks users, continues an interrupted import, and undoes one.
- [Account linking](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/account-linking.md): Learn how Clerk links a social sign-in to an imported user.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)
