Index of every page on this site: llms.txt
All skills
clerk avatar

/clerk-migrate

@95f241a official
by clerkclerk/skills95 stars
6
Run it yourself

Migrate users into Clerk from another auth provider, or between Clerk instances, using the `clerk migrate` command family. Use when the user says "migrate my users to Clerk", "import users from Auth0 / Supabase / Firebase / Auth.js / Better Auth / WorkOS", "export my users", "move users from development to production", "undo the import", or hands over a user export file (JSON or CSV) and asks what to do with it. Covers exporting from the auth platform, choosing a source, writing one for a platform with no built-in, checking and running the import, inspecting runs, and undoing one. Don't use for adding Clerk to an app (use clerk-setup) or for general CLI tasks (use clerk-cli).

Use this Skill: https://skilld.dev/gh/clerk/skills/clerk-migrate

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesruns.md

≈1.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Runs, re-running, and undo

Every export, import and undo is a run: a folder holding what it did, user by user. clerk migrate runs reads them, re-running an import continues one, and clerk migrate undo reverses one.

Re-running an import

Running the same import again continues it. The CLI matches on the file's sha256, the source (a custom source by its file hash), and the instance ID:

Latest matching run Re-running does
none starts a new run
interrupted continues the same run, skipping the users it created
partial continues the same run, retrying the users that failed or were rejected. Users the source skipped stay skipped.
complete nothing; prints "Already imported in run …" and exits 0
undone starts a new run

--new-run skips the lookup and forces a fresh run.

Only one import of a file into an instance runs at a time. A second one exits 2 while the first is live, whatever source or --runs-dir it uses, and names the lock file. A Ctrl-C or a crash can leave the lock behind; the next import reclaims it. The file is safe to delete when no clerk migrate import is running.

A re-run refuses with exit 2, and imports nothing, when:

  • another process holds the run, or is importing this same file into the same instance
  • the same file went into this instance under a different source, or an earlier version of a source you wrote, and that run was not undone. Undo it, or pass --new-run to import alongside it. The source's hash covers only its own file, not local files it imports.
  • an undo of the matching run is unfinished. Finish the undo first.
  • Clerk did not confirm which instance the key addresses (a stand-in key_… ID), and a run of this file exists under a real instance ID, so the CLI cannot tell whether it is the same instance. Try again, or pass --new-run.
  • a Firebase run is continued with different hash parameters
  • --reserve-unverified is passed to continue a run created without it. A continue keeps the mode the run recorded.

Importing an export run by its ID into the instance it was exported from is refused too: every user is already there.

Run files

clerk migrate runs                        # every run, newest first
clerk migrate runs 20260929-141502-a1b2   # one run in full
clerk migrate runs --json

Each run folder holds run.json (kind, status, target, source, file and its sha256, counts, flags) and users.ndjson, one line per user outcome. A line carries sourceId, clerkId and status, plus reason, error, code, passwordDropped, reserved or pending when they apply. The last line for each sourceId wins.

status Means
created Clerk created the user. pending lists identifiers still to attach.
creating sent, with no confirmed answer. runs shows it as "not confirmed".
failed Clerk refused the create. error and code say why.
skipped left out: by the source (code: "source_skip"), by a reject under --allow-partial, or by --require-password. reason says why.
deleted removed by an undo
exported written by an export run

Grep it directly:

grep '"status":"failed"' .clerk/migrate/<run-id>/users.ndjson

A run is partial when any user failed, was skipped, was not confirmed, was not sent, or has identifiers left to attach, and complete otherwise. A user its source skipped (code: "source_skip") doesn't count. A run whose only skips are those is complete. A run whose process died before recording a finish time is interrupted, but only clerk migrate runs works that out: its run.json still says running. Read run.state from runs <run-id> --json (or runs[].state from runs --json) rather than status from run.json.

A run records the instance ID from GET /v1/instance. When that call fails and nothing else names the instance, it records key_<hash> instead.

Undoing an import

clerk migrate undo <run-id> --dry-run    # preview: how many, and how many signed in since
clerk migrate undo <run-id> --yes
clerk migrate undo <run-id> --yes --include-signed-in

undo deletes only the users that run created: the Clerk IDs it recorded, plus any create it never confirmed, found by external_id and the run's clerkMigrateRun marker. Users the import did not create stay untouched.

Show the user the preview, including how many imported users have signed in since, and get a yes before passing --yes. --yes alone does not delete users who signed in since the import. If there are any, it exits 2 and deletes nothing, and --json prints "includeSignedIn": "required". Those are accounts people have used: pass --include-signed-in only after the user says yes to deleting them too. A user who signs in between the preview and the delete also stops the undo; run it again to see the new preview.

It refuses with exit 2, and deletes nothing, when:

  • the key addresses a different instance than the run imported into
  • Clerk could not confirm the instance (a stand-in key_… ID on the run or for the current key), unless the run was recorded with this same key. Try again in a minute.
  • the run is not an import (an export or an undo run)
  • the run is already undone
  • the import is still running in another process
  • the run changed during the preview

A partial undo exits 1. Running undo again retries the users that failed, in the same undo run. The import is marked undone only when every user is deleted.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings3d3 checks · Risk MEDIUM
  • Gen Agent Trust Hub3d

    The skill facilitates user migrations to Clerk. It includes features for generating custom transformation scripts and analyzing user data files, which present potential security surfaces. It follows strong security practices for credential handling and user consent.

  • Socket3d

    No alerts

  • Snyk3d

    Risk: MEDIUM · 1 issue

Signed by skilld at 95f241a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 days ago
What it can do
Runs commands Reads files Edits files
metadata
{
  "author": "clerk",
  "version": "1.0.0"
}
All 5 allowed tools
BashReadWriteGrepGlob
Other metadata
compatibility
Requires the `clerk` CLI binary 4.2.0 or later (npm package `clerk`, or `bunx clerk@latest`), the first release with the `clerk migrate` command family. Needs a Clerk session from `clerk auth login`, or a Backend API secret key passed with `--secret-key`. No other dependency: do not install an SDK or a database driver.

README badge

README badge for clerk/skills/clerk-migrate