Skip to main content

The Clerk CLI exports your users from Firebase Authentication with clerk migrate export firebase, then creates them in Clerk with clerk migrate import. Firebase's password hashes come across intact, so your users keep the passwords they already have.

Migrate with an AI agent

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.

What you need

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.

A Firebase service account key

The export talks to Firebase's Identity Toolkit directly, so it needs a service account key rather than a firebase login session.

  1. In the Firebase console, open your project, go to Project settings, and select the Service accounts tab.
  2. Select Generate new private key, then confirm. A JSON file downloads.
  3. Save it next to where you'll run the migration, as service-account.json.

The service account needs to list users and read the project's password hash parameters. The Firebase Authentication Admin role covers both. For read-only access, grant Firebase Authentication Viewer plus a custom role with the firebaseauth.configs.getHashConfig permission. Without that permission, Firebase redacts the password hashes. If the CLI warns about redacted hashes, grant the permission and export again. If it receives hashes but can't read the hash parameters, supply the parameters manually.

Warning

A service account key is a credential for your whole Firebase project. Keep it out of version control and delete it once the migration is done.

Pass --service-account the key file's path, not its JSON. If you pass the JSON, it shows up in ps, even when it comes from "$VAR" or "$(cat key.json)". If you type it, it also lands in your shell history. In CI, write the key to a file only the job can read and pass its path.

What migrates

  • Passwords: The import needs both a hash and a salt. For a user with only one of the two, the import drops both and creates the user without a password.
  • Disabled accounts: The import bans a Firebase user with disabled: true.
  • Unverified emails: They stay unverified by default. Firebase's emailVerified decides where an address lands. Clerk creates primary identifiers as verified, so the import keeps an address Firebase never confirmed off the primary fields and attaches it as unverified. The checks reject a user whose only email is unverified when your instance requires an email. To reserve those unverified addresses instead, see unverified emails and phones.
  • Phone numbers: The import adds them as verified. Firebase has no phone-verified field, since users confirm a number by SMS.
  • Display names: displayName becomes a first name, from the first word, and a last name, from the rest. The source omits a one-word displayName that matches the user's own email.
  • Signup dates: The import keeps the date from Firebase's createdAt.
  • Firebase IDs: Each user's localId becomes the Clerk user's external_id, which is how a re-run recognizes the users it already created. To keep referencing it in your app, see foreign keys.

What doesn't migrate

  • Social accounts, custom claims, and sign-in timestamps: The export omits these, along with Firebase's provider records. A user who only ever signed in with Google arrives with their email address and no password. Enable the same providers on the SSO connections page in the Clerk Dashboard. When a user signs in with one, Clerk links it to their imported account by verified email address. Clerk doesn't link to an address the import attached as unverified, so that sign-in creates a separate user. To link those users, import with --reserve-unverified. If you reserve the address and the provider doesn't confirm it, Clerk asks the user to verify it before linking. See account linking.
  • Multi-factor authentication (MFA) enrollments: Users must enroll again in Clerk.

Export your users from Firebase

Run the export with your service account key:

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

If you leave off --service-account, the CLI asks for the key. Enter the file's path or paste the key's JSON, which lets you use a key from a password manager without saving it to disk. The CLI checks the key before it sends anything to Google. If you pass a web app config to --service-account, the CLI reports the missing field and exits. At the interactive prompt, it reports the error and asks again. If Google rejects the key, an interactive run asks for it again. With --yes, --json, in an agent run, or without a terminal, pass --service-account the key file's path, because the export doesn't prompt. The CLI never reads GOOGLE_APPLICATION_CREDENTIALS.

If FIREBASE_AUTH_EMULATOR_HOST is set in your shell, the export reads the Firebase emulator instead of your project, and the target line says so. Unset it before you export your real users.

The export saves your users as export.json in a new run, and prints the run ID and a field coverage table, so you see what the data contains before importing it:

Field coverage
  ✓ 412/412 have an email address
  ! 388/412 have a verified email
  ! 341/412 have a password hash
  ! 120/412 have a display name
  ✗ 0/412 have a phone number

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

Firebase uses a modified scrypt, so Clerk can't verify a digest without the project's four hash parameters. The export reads them from the project and saves them in the export file, so the import needs no extra flags:

Password hash parameters
Read from the project and saved in the export file, so the import needs nothing more.

The export file sits in the run folder, which the CLI adds to .gitignore, because the signer key is a Firebase secret. If you pass -o or keep runs somewhere else, keep that file out of git yourself. An export with no password hashes needs no parameters and says so instead.

Either of these warnings means some users will import without a password and need to reset it:

  • A password hash came back redacted. The service account can't read hashes. Grant it firebaseauth.configs.getHashConfig and export again.
  • A user has a password Firebase didn't return. Firebase returns only hashes it made itself, so users you imported into Firebase with bcrypt, HMAC, or another hasher come back without one.

If the export couldn't read the hash parameters

When the service account can't read the parameters, or the project's parameters are ones Clerk can't use, the export still succeeds without them and says so. Get them from the console:

  1. In the Firebase console, navigate to Authentication and select the Users tab.
  2. Select the three vertical dots above the user list, then select Password hash parameters.
  3. Copy base64_signer_key, base64_salt_separator, rounds, and mem_cost, and enter them when the import asks.

All four are required as a set. Supplying some but not all is a usage error naming what's missing. The import also refuses parameters Clerk can't use, such as a key that isn't base64, or rounds or mem_cost outside 1 to 16. The flags override parameters saved in the export file, so you can pass a rotated key without exporting again. Continuing a run with different parameters is refused, so pass --new-run to change them partway through.

In a terminal, the import asks for each parameter, with the signer key masked. A --yes run never asks, so for the real import either leave off --yes and confirm at the prompt, or set CLERK_FIREBASE_SIGNER_KEY, CLERK_FIREBASE_SALT_SEPARATOR, CLERK_FIREBASE_ROUNDS, and CLERK_FIREBASE_MEM_COST. The same applies with --json, in an agent run, or without a terminal. The --firebase-signer-key, --firebase-salt-separator, --firebase-rounds, and --firebase-mem-cost flags still work, but they put the signer key in your shell history. The variables apply only when the export file doesn't include the parameters.

If you already have a firebase auth:export file

The firebase source reads what the Firebase CLI produces, in either format, so an existing export file can skip clerk migrate export entirely:

terminal
firebase auth:export firebase-users.json --format=json --project <firebase_project_id>

--format=csv works too. The CSV Firebase writes has no header row, and the source supplies the column names. Either way, the file doesn't name its source, so pass --source firebase, and get the hash parameters from the console, since only clerk migrate export firebase reads them from the project:

terminal
clerk migrate import firebase-users.json --source firebase --dry-run

Import your users into Clerk

The source skips users with neither email nor phone, including anonymous users. The import records them as skipped and continues without requiring --allow-partial.

Check the export against your Clerk instance 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, or --reserve-unverified to preview reserving unverified emails and phones:

terminal
clerk migrate import <export_run_id> --dry-run

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.

After the checks pass, rerun the same command with --yes instead of --dry-run, keeping the input 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, run the same command again.

An export from clerk migrate export firebase also includes the hash parameters, so you don't pass any --firebase-* flags.

Verify the migration

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

    terminal
    clerk migrate runs <import_run_id>
  2. Confirm the users exist in Clerk:

    terminal
    clerk users list
  3. Sign in as one of them with their Firebase password. The import can succeed with incorrect hash parameters, and users then can't sign in. Only a sign-in confirms the parameters were right.

Undo the migration

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

terminal
clerk migrate undo <import_run_id> --dry-run

Then delete them:

terminal
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 for confirmation rules, refusal conditions, and retries.

Next steps

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