feat(migrate): make clerk migrate generally available by royanger · Pull Request #594 · clerk/cli

royanger · 2026-10-28T20:42:53Z

PR 14 of 14 for clerk migrate (plan: slice-prs.md on #479). Stacked on #531: review that first, then this one, which shows only its own diff. It removes the CLERK_EXPERIMENTAL=migrate gate, so clerk migrate shows in clerk --help and completion.

These commits were the start of #531 until it was split; they're unchanged.

Try it

clerk --help
clerk migrate --help
clerk migrate import users.json --source supabase --dry-run

What it does

Deletes lib/experimental.ts, the gate stub, ERROR_CODE.EXPERIMENT_DISABLED, and every CLERK_EXPERIMENTAL setup in tests.
Adds migrate to the root README's help output.
Checks commands/migrate/README.md against every subcommand's --help and fixes the drift.
The changeset announces clerk migrate, and drops "still experimental" from the earlier migrate changesets that haven't shipped yet.
Public docs: clerk/clerk#3351 documents clerk migrate and its guides. It merges after this ships.

Tests

bun run test covers the unit and integration tests.
The live slice suite (pnpm test:migrate:slice6) runs an import and its undo with CLERK_EXPERIMENTAL unset.

🤖 Generated with Claude Code

changeset-bot · 2026-10-28T20:42:59Z

🦋 Changeset detected

Latest commit: 6c26329

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-10-28T20:43:01Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Organization UI
Review profile: ASSERTIVE
Plan: Team
Run ID: 6d6b7ddc-a59d-48fc-b079-172f46e15a53

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

manovotny · 2026-10-30T17:03:18Z

    packages: ["passport"],
    name: "Passport.js",
-    docsUrl: "https://clerk.com/docs/migrations/overview",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/custom-source",


clerk init now sends Passport and Kinde users to the custom-source docs page, but clerk migrate sources and the custom-source errors still link the GitHub README (CUSTOM_SOURCES_URL in sources/load-custom.ts). Move that to the docs page too, so both point at one guide?

Already done in 08d4197, which hadn't been pushed when you reviewed. CUSTOM_SOURCES_URL now points at https://clerk.com/docs/guides/development/migrating/custom-source, so clerk init, clerk migrate sources, the --source help and every custom-source error link the same guide.

manovotny · 2026-10-30T17:03:18Z

+      const names = result.completions.map((c) => c.name);
+      expect(names).toContain("supabase");
+      expect(names).toContain("workos");
    });


With gate.test.ts gone, nothing checks that completion offers migrate or its subcommands. Maybe add one like the security test?

Suggested change

});

});

test("completes migrate subcommands", () => {

expect(completionNames("")).toContain("migrate");

expect(completionNames("migrate", "")).toEqual(

expect.arrayContaining(["import", "export", "undo", "runs", "sources"]),

);

});

manovotny · 2026-10-30T17:03:18Z

+
+Make `clerk migrate` available without `CLERK_EXPERIMENTAL=migrate`: it now shows in `clerk --help` and shell completion.
+
+- `clerk migrate export` gets users out of Clerk, Supabase, Firebase, Auth0, WorkOS, Better Auth or Auth.js into a run, and `clerk migrate import` checks every user against your instance, asks before it writes, and continues a run that stopped partway.


[Nit] Oxford comma before "or Auth.js"? Same for "passwords, MFA and metadata" in migrate-custom-sources.md.

Suggested change

- `clerk migrate export` gets users out of Clerk, Supabase, Firebase, Auth0, WorkOS, Better Auth or Auth.js into a run, and `clerk migrate import` checks every user against your instance, asks before it writes, and continues a run that stopped partway.

- `clerk migrate export` gets users out of Clerk, Supabase, Firebase, Auth0, WorkOS, Better Auth, or Auth.js into a run, and `clerk migrate import` checks every user against your instance, asks before it writes, and continues a run that stopped partway.

manovotny · 2026-10-30T17:03:18Z

-pasted unencoded (`#`, `@`, `/` and the like) is percent-encoded for you.
+pasted unencoded (`#`, `@`, `/` and the like) is percent-encoded for you. A libsql
+token comes from `?authToken=` on the URL, or from `TURSO_AUTH_TOKEN` /
+`LIBSQL_AUTH_TOKEN`, and is redacted like a password.


[Nit] Active voice reads a little clearer here.

Suggested change

`LIBSQL_AUTH_TOKEN`, and is redacted like a password.

`LIBSQL_AUTH_TOKEN`, and the CLI redacts it like a password.

manovotny · 2026-10-30T17:03:18Z

@@ -1,27 +0,0 @@
-/**


Thoughts on keeping lib/experimental.ts instead of deleting it? migrate was its only user, but I doubt it's the last thing we'll want to gate. Keeping it means the next one is a couple of lines, not a dig through git history. Not a blocker either way.

manovotny · 2026-10-30T17:03:18Z

 ```
-clerk migrate export [source] [-o <path>] [--json]
-clerk migrate import <file|export-run-id> [--source <source>] [--dry-run] [--allow-partial] [--new-run] [--yes] [--json]
+clerk migrate export [platform] [-o <path>] [--json]


[Nit] Everywhere else in --help, "source" means the import-side mapper (--source, clerk migrate sources). Maybe drop it from export's description (export/index.ts:99), e.g. "Export users from an auth platform, ready for clerk migrate import", so it only ever means one thing?

Remove the CLERK_EXPERIMENTAL=migrate gate. `clerk migrate` now registers like every other command, so it shows in `clerk --help` and completion and runs without an env var. Drops lib/experimental.ts, the experiment_disabled error code, the gate test, and the env setup in tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Add `migrate` to the root README's help output. In the migrate README, show `export [platform]` and `import [file|export-run-id]` as optional the way `--help` does, say `sources` takes no `--runs-dir`, match the export `-y` wording, and restore the libsql token sentence. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…er changesets None of them has shipped, and this slice makes migrate generally available, so the release notes would have said "still experimental" beside the entry announcing it. Lands only with the flip. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

`clerk init`'s auth-library scan and `clerk migrate export workos` linked to the old `/docs/migrations/*` pages or the migration overview. They now link to the guide for each platform under `/docs/guides/development/migrating/`: authjs, auth0, supabase, firebase, better-auth and workos. Passport.js and Kinde have no built-in source, so they link to the custom-source guide. URL strings only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

`CUSTOM_SOURCES_URL` linked to the "Custom sources" section of the CLI's README on GitHub. Errors from a source you wrote, `clerk migrate sources`, and the `--source` help now link to the custom-source guide under /docs/guides/development/migrating/, which covers the same validation errors and hook signatures for someone migrating, not developing the CLI. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

royanger added a commit that referenced this pull request Oct 28, 2026

docs: record the final slice as #594

3e551d5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

royanger force-pushed the migrate/final-slice branch from 7023aa6 to bef6085 Compare October 28, 2026 21:48

royanger marked this pull request as ready for review October 28, 2026 22:12

royanger force-pushed the migrate/slice-6 branch from 76d2b5f to a3192a5 Compare October 28, 2026 22:29

royanger force-pushed the migrate/final-slice branch from bef6085 to 3e7f420 Compare October 28, 2026 22:29

royanger force-pushed the migrate/slice-6 branch from a3192a5 to 3ad0320 Compare October 28, 2026 22:58

royanger force-pushed the migrate/final-slice branch 2 times, most recently from 10e434a to dfdb627 Compare October 28, 2026 23:11

royanger force-pushed the migrate/slice-6 branch from 769c96e to c662cdc Compare October 28, 2026 23:14

royanger force-pushed the migrate/final-slice branch from dfdb627 to 5c23bdf Compare October 28, 2026 23:14

royanger requested review from manovotny and wyattjoh October 29, 2026 18:03

manovotny self-assigned this Oct 30, 2026

manovotny added the do not merge label Oct 30, 2026

manovotny reviewed Oct 30, 2026

View reviewed changes

manovotny mentioned this pull request Oct 30, 2026

Add a clerk-migrate skill for moving users into Clerk clerk/skills#73

Open

royanger and others added 6 commits October 30, 2026 15:39

docs(changeset): Make clerk migrate available without CLERK_EXPERIMENTAL

01f5aa8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

royanger force-pushed the migrate/final-slice branch from 08d4197 to 6c26329 Compare October 30, 2026 19:43

royanger changed the base branch from migrate/slice-6 to migrate/telemetry October 30, 2026 19:49

Navigation Menu

Repository navigation

feat(migrate): make clerk migrate generally available - #594

feat(migrate): make clerk migrate generally available#594
royanger wants to merge 6 commits into
migrate/telemetryfrom
migrate/final-slice

royanger commented Oct 28, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Oct 28, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 28, 2026 •

edited

Loading

Review skipped

Uh oh!

manovotny Oct 30, 2026

Uh oh!

royanger Oct 30, 2026

Uh oh!

manovotny Oct 30, 2026

Uh oh!

manovotny Oct 30, 2026

Uh oh!

manovotny Oct 30, 2026

Uh oh!

manovotny Oct 30, 2026

Uh oh!

manovotny Oct 30, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-    });
+    });
+    test("completes migrate subcommands", () => {
+      expect(completionNames("")).toContain("migrate");
+      expect(completionNames("migrate", "")).toEqual(
+        expect.arrayContaining(["import", "export", "undo", "runs", "sources"]),
+      );
+    });


		Make `clerk migrate` available without `CLERK_EXPERIMENTAL=migrate`: it now shows in `clerk --help` and shell completion.

		- `clerk migrate export` gets users out of Clerk, Supabase, Firebase, Auth0, WorkOS, Better Auth or Auth.js into a run, and `clerk migrate import` checks every user against your instance, asks before it writes, and continues a run that stopped partway.

	`LIBSQL_AUTH_TOKEN`, and is redacted like a password.
	`LIBSQL_AUTH_TOKEN`, and the CLI redacts it like a password.

Conversation

royanger commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Try it

What it does

Tests

Uh oh!

changeset-bot Bot commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

manovotny Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

royanger Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

manovotny Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

manovotny Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

manovotny Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

manovotny Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

manovotny Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

royanger commented Oct 28, 2026 •

edited

Loading

changeset-bot Bot commented Oct 28, 2026 •

edited

Loading

coderabbitai Bot commented Oct 28, 2026 •

edited

Loading