From 000dde884f144425a6095fcb8f3bc9b4d3ec0a9b Mon Sep 17 00:00:00 2001 From: Michael Novotny Date: Wed, 28 Oct 2026 10:11:26 -0500 Subject: [PATCH 1/2] feat(users): point users --help to clerk migrate People looking for bulk import or migration often check `clerk users` first. End its help with a pointer to `clerk migrate`. Co-Authored-By: Claude Opus 5.5 --- .changeset/users-help-migrate-hint.md | 5 ++++ packages/cli-core/src/cli-program.test.ts | 30 +++++++++++++++++++ .../cli-core/src/commands/users/README.md | 2 ++ packages/cli-core/src/commands/users/index.ts | 6 ++++ 4 files changed, 43 insertions(+) create mode 100644 .changeset/users-help-migrate-hint.md diff --git a/.changeset/users-help-migrate-hint.md b/.changeset/users-help-migrate-hint.md new file mode 100644 index 000000000..84c3ee381 --- /dev/null +++ b/.changeset/users-help-migrate-hint.md @@ -0,0 +1,5 @@ +--- +"clerk": patch +--- + +Point `clerk users --help` to `clerk migrate` for bringing users in from another provider. diff --git a/packages/cli-core/src/cli-program.test.ts b/packages/cli-core/src/cli-program.test.ts index fe8e4b14a..421ac6b72 100644 --- a/packages/cli-core/src/cli-program.test.ts +++ b/packages/cli-core/src/cli-program.test.ts @@ -247,6 +247,36 @@ test("users create documents -d and --file for raw BAPI request bodies", () => { expect(help).toContain("--file"); }); +describe("users --help", () => { + const captured = useCaptureLog(); + + // People who want to bulk-import users look under `clerk users` first. + // `helpInformation()` leaves out text added with `addHelpText`, so render + // the whole help screen instead. + test("points bulk imports to clerk migrate", () => { + const program = createProgram(); + const users = program.commands.find((command) => command.name() === "users")!; + users.outputHelp(); + + expect(captured.out.trimEnd()).toEndWith( + [ + "", + "To bring users in from another provider (Auth0, Firebase, Supabase and more),", + "use `clerk migrate`.", + ].join("\n"), + ); + }); + + test("leaves the hint off the subcommands", () => { + const program = createProgram(); + const users = program.commands.find((command) => command.name() === "users")!; + const list = users.commands.find((command) => command.name() === "list")!; + list.outputHelp(); + + expect(captured.out).not.toContain("clerk migrate"); + }); +}); + describe("formatApiBody", () => { // --- Single error with meta --- diff --git a/packages/cli-core/src/commands/users/README.md b/packages/cli-core/src/commands/users/README.md index a49d24ca4..520f145a1 100644 --- a/packages/cli-core/src/commands/users/README.md +++ b/packages/cli-core/src/commands/users/README.md @@ -2,6 +2,8 @@ Manage direct Clerk user resources with first-class commands. Use `clerk api` for unsupported or fully custom user requests. +To bring users in from another provider (Auth0, Firebase, Supabase and more), use [`clerk migrate`](../migrate/README.md). `clerk users --help` ends with the same pointer. + Works with no login and no linked project on an **unclaimed accountless application** — the one an SDK creates for itself the first time you run `next dev` (or similar) with no keys configured. See diff --git a/packages/cli-core/src/commands/users/index.ts b/packages/cli-core/src/commands/users/index.ts index fdb5a9a9f..60cb16130 100644 --- a/packages/cli-core/src/commands/users/index.ts +++ b/packages/cli-core/src/commands/users/index.ts @@ -54,6 +54,12 @@ export function registerUsers(program: Program): void { description: "Create a user from an inline BAPI request body", }, ]) + .addHelpText( + "after", + ` +To bring users in from another provider (Auth0, Firebase, Supabase and more), +use \`clerk migrate\`.`, + ) .action(async (_opts, cmd) => users.menu(cmd.optsWithGlobals() as Parameters[0]), ); From fe0ef4701288caa03b6f18ca4a03a5717abefd44 Mon Sep 17 00:00:00 2001 From: Michael Novotny Date: Wed, 28 Oct 2026 10:33:50 -0500 Subject: [PATCH 2/2] fix(users): use an Oxford comma in the migrate hint Co-Authored-By: Claude Opus 5.5 --- packages/cli-core/src/cli-program.test.ts | 2 +- packages/cli-core/src/commands/users/README.md | 2 +- packages/cli-core/src/commands/users/index.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/cli-core/src/cli-program.test.ts b/packages/cli-core/src/cli-program.test.ts index 421ac6b72..e79f58db0 100644 --- a/packages/cli-core/src/cli-program.test.ts +++ b/packages/cli-core/src/cli-program.test.ts @@ -261,7 +261,7 @@ describe("users --help", () => { expect(captured.out.trimEnd()).toEndWith( [ "", - "To bring users in from another provider (Auth0, Firebase, Supabase and more),", + "To bring users in from another provider (Auth0, Firebase, Supabase, and more),", "use `clerk migrate`.", ].join("\n"), ); diff --git a/packages/cli-core/src/commands/users/README.md b/packages/cli-core/src/commands/users/README.md index 520f145a1..bb386ccbb 100644 --- a/packages/cli-core/src/commands/users/README.md +++ b/packages/cli-core/src/commands/users/README.md @@ -2,7 +2,7 @@ Manage direct Clerk user resources with first-class commands. Use `clerk api` for unsupported or fully custom user requests. -To bring users in from another provider (Auth0, Firebase, Supabase and more), use [`clerk migrate`](../migrate/README.md). `clerk users --help` ends with the same pointer. +To bring users in from another provider (Auth0, Firebase, Supabase, and more), use [`clerk migrate`](../migrate/README.md). Works with no login and no linked project on an **unclaimed accountless application** — the one an SDK creates for itself the first time you run diff --git a/packages/cli-core/src/commands/users/index.ts b/packages/cli-core/src/commands/users/index.ts index 60cb16130..9f2e4cefd 100644 --- a/packages/cli-core/src/commands/users/index.ts +++ b/packages/cli-core/src/commands/users/index.ts @@ -57,7 +57,7 @@ export function registerUsers(program: Program): void { .addHelpText( "after", ` -To bring users in from another provider (Auth0, Firebase, Supabase and more), +To bring users in from another provider (Auth0, Firebase, Supabase, and more), use \`clerk migrate\`.`, ) .action(async (_opts, cmd) =>