Skip to main content

The Clerk CLI exports your users from the auth.users table in your Supabase Postgres database with clerk migrate export supabase, then creates them in Clerk with clerk migrate import.

The export reads the database, not Supabase's Admin API, because encrypted_password exists only in the table. The password digests come across, 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 connection string for your Supabase database

  1. In the Supabase dashboard, open your project and select Connect.
  2. Copy the Session pooler connection string.
  3. Substitute your database password into it.

Important

Use the pooler string. Supabase's direct connections are IPv6-only unless you've bought the IPv4 add-on, so a direct string typically fails to connect from a laptop or a build server.

Connect as the postgres role. An application role usually can't read the auth schema, and the export needs to.

What migrates

  • Supported password hashes: Supabase hashes with bcrypt by default, and accepts argon2 hashes from its own imports, so the supabase source detects the hasher per user: bcrypt, argon2id, or argon2i. The source omits a hash Clerk can't verify, such as one from another hasher or a bcrypt hash with a cost above 15, and the checks warn that the user will import without a password.
  • Unverified emails and phones: They stay unverified by default. Supabase records verification as a timestamp that stays null until the user confirms. The import attaches an email with no email_confirmed_at as unverified and keeps it off the primary fields. The same applies to phone_confirmed_at. 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.
  • Names from metadata: auth.users has no name columns. The name lives in raw_user_meta_data under whichever key the provider used. The source uses first_name and last_name as they are. When there's no first name, the supabase source splits display_name, full_name, or name, in that order, into first and last name.
  • Discord names: The source removes a trailing # and digits from names such as name#0 because Clerk interprets that suffix as a URL.
  • Phone numbers: Supabase stores phone numbers in E.164, the international telephone numbering standard, without the leading +. The source adds the + Clerk requires.
  • Active bans: The import bans a user whose banned_until is still in the future. Clerk's bans have no end date, so a temporary ban stays until you lift it in Clerk, and the checks warn you about it.
  • Supabase IDs: Each user's id 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.
  • User metadata: raw_user_meta_data becomes unsafeMetadata. Your users could edit it in Supabase, and they can still edit it in Clerk. Don't trust it on the server.
  • Signup dates: The import keeps the date from created_at.

What doesn't migrate

  • Multi-factor authentication (MFA) enrollments: Users must enroll again in Clerk.
  • App metadata: The import omits raw_app_meta_data.
  • Social accounts: 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.

Export your users from Supabase

Run the export, and enter your connection string, postgresql://postgres.<project_ref>:<password>@<pooler_host>:5432/postgres, when the CLI asks:

terminal
clerk migrate export supabase

Without --db-url, the CLI reads SUPABASE_DB_URL, then prompts for it. The prompt masks what you type, and a value entered at a prompt stays out of your shell history. If the database rejects the connection string, the prompt explains why and asks again. With --yes, --json, in an agent run, or without a terminal, the export doesn't prompt, and fails if the connection string is missing or rejected.

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

Field coverage
  ✓ 412/412 have an email address
  ! 388/412 have a confirmed email
  ! 341/412 have a password hash
  ✗ 0/412 have a phone number
  ! 260/412 have a first name
  ! 120/412 have a last name

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

If the password hash row is far below the user count, most of your users signed up through a social provider rather than with a password. Before importing, review the social provider requirements.

If the connection fails

The CLI adds troubleshooting guidance below the database error:

What you seeWhat to check
Could not reach the databaseThe host and port. Use the pooler connection string, or enable the IPv4 add-on under Settings > Add-Ons
The database rejected those credentialsThe user and password in the connection string
The auth.users table was not readableThat Supabase Auth is enabled, and that you're connecting as postgres rather than an application role

A password containing characters such as @, #, or / usually doesn't need URL-encoding: the CLI encodes a password it can't otherwise parse. If the connection still fails, URL-encode the password. Connection strings are redacted in every error message, including when the password itself contains an unencoded @.

Import an auth.users file you already have

The supabase source also reads a JSON or CSV export of auth.users that you made yourself, such as from the SQL editor. A file you wrote doesn't name its source, so pass --source supabase:

terminal
clerk migrate import <path> --source supabase --dry-run

Include encrypted_password to keep passwords, and raw_app_meta_data for the social provider check. Without raw_app_meta_data, that check doesn't run.

Import your users into Clerk

Soft-deleted and anonymous users

The source skips soft-deleted (deleted_at) and anonymous (is_anonymous) users. The import records them as skipped and continues without requiring --allow-partial.

Users whose only social provider is disabled in Clerk

If Discord is disabled in Clerk, a user who signed in only with Discord needs another enabled sign-in method. The checks reject users who have none.

The checks read each user's raw_app_meta_data.providers and compare it against the social providers your destination instance has enabled. A user passes if any of these is true:

  • One of their providers is enabled in Clerk, or is Supabase's own email or phone provider.
  • They have a verified email and the instance signs in by email code or email link, or a verified phone and the instance signs in by SMS code. An unverified email or phone counts only if you reserve it with --reserve-unverified or answer yes to the reservation prompt. A dry run doesn't ask, so it counts them only when you pass the flag. An email Clerk refuses, such as one with a .local domain, doesn't count.
  • Supabase recorded no providers for them.

The checks reject everyone else, naming each provider as either "not enabled in Clerk" or "not offered by Clerk". Enable the missing social connections in Clerk and run the checks again. Providers Clerk doesn't offer can't be enabled, so to leave those users behind, pass --allow-partial. The import records them as skipped.

The CLI still warns about providers that are disabled or unavailable in Clerk, even when their users have another valid sign-in method.

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.

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 Supabase password. Only a sign-in confirms the digests came across intact.

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