feat(deploy): added deploy wizard

.agents/skills/audit-clerk-skill

@@ -0,0 +1 @@
+../../.claude/skills/audit-clerk-skill

.agents/skills/changesets

@@ -0,0 +1 @@
+../../.claude/skills/changesets

.changeset/deploy-status.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk deploy status`, a read-only command that verifies a production deploy, including DNS, SSL, email DNS, and OAuth credential completeness. Agent-mode `clerk deploy` now emits a tailored read-only handoff instead of a hard usage error.

.changeset/deploy-wizard.md

@@ -0,0 +1,12 @@
+---
+"clerk": minor
+---
+
+Add `clerk deploy`, an interactive wizard that promotes a Clerk application from development to production.
+
+- Walks through cloning the development instance, creating the production instance, and configuring CNAME records.
+- Verifies mail, DNS, and SSL one component at a time so each step's status is visible while polling.
+- Optionally exports the DNS records as a BIND zone file at `./clerk-<domain>.zone` for import into providers like Cloudflare, Route 53, and Google Cloud DNS.
+- Resumes from the next pending step on subsequent runs, including reshowing the CNAME records when DNS is not yet verified.
+- Uses provider schemas to collect production OAuth credentials for broader built-in provider support.
+- Returns users to credential choices after opening provider docs, including Google JSON import when supported.

.claude/rules/logging.md

@@ -15,17 +15,17 @@ Adjust the relative path to `lib/log.ts` based on the file's location under `pac
 
 ## Which method to use
 
-| Method          | Stream     | When to use                                     |
-| --------------- | ---------- | ----------------------------------------------- |
-| `log.data()`    | **stdout** | Pipeable output (JSON, lists, machine-readable) |
-| `log.info()`    | stderr     | Status messages                                 |
-| `log.success()` | stderr     | Completion confirmations (green)                |
-| `log.warn()`    | stderr     | Warnings (yellow)                               |
-| `log.error()`   | stderr     | Errors (red, auto-prefixed `error:`)            |
-| `log.debug()`   | stderr     | Diagnostic info, only with `--verbose`          |
-| `log.raw()`     | stderr     | Machine-readable JSON for agent mode            |
+| Method          | Stream     | When to use                                      |
+| --------------- | ---------- | ------------------------------------------------ |
+| `log.data()`    | **stdout** | Pipeable output (JSON, lists, machine-readable)  |
+| `log.info()`    | stderr     | Status messages                                  |
+| `log.success()` | stderr     | Completion confirmations (green)                 |
+| `log.warn()`    | stderr     | Warnings (yellow)                                |
+| `log.error()`   | stderr     | Errors (red, auto-prefixed `error:`)             |
+| `log.debug()`   | stderr     | Diagnostic info, only with `--verbose`           |
+| `log.raw()`     | stderr     | Machine-readable JSON for agent mode             |
 | `log.ui()`      | stderr     | Pre-formatted UI (spinner, intro/outro brackets) |
-| `log.blank()`   | stderr     | Blank line                                      |
+| `log.blank()`   | stderr     | Blank line                                       |
 
 `log.data()` writes to **stdout** — this is what gets piped (e.g., `clerk apps list | jq`). Everything else writes to **stderr** as UI for humans. Never mix these.
 

.claude/rules/testing.md

@@ -24,6 +24,8 @@ bun run test
 
 This runs each unit and integration test file as a separate `bun test` subprocess via `scripts/run-tests.ts`, isolating module state between files. E2E fixtures are excluded and require separate setup (see `rules/e2e.md`).
 
+When running multiple test files directly with `bun test`, always pass `--isolate` or `--parallel`. `--parallel` implies `--isolate`. Without isolation, Bun can share module mocks across files and produce order-dependent failures.
+
 Prefer `spyOn()` for mocking, and always restore spies in `afterAll` with `mockRestore()`.
 
 Never use `for` or `forEach` loops inside a single test to verify multiple inputs or cases — use `test.each` (or `it.each` / `describe.each`) so each case is its own reported test case with its own name, setup/teardown, and pinpointed failure output.

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -52,6 +52,8 @@ Locally, prefer `bun run test:e2e:op` so secrets are injected from 1Password in-
 
 CI runs `bun run format:check` (fails if unformatted), `bun run lint`, `bun test`, and `bun run test:e2e` on every PR to `main`. E2E tests only run for PRs from the same repository (not external forks) and target the production Clerk API with a dedicated test application.
 
+When running multiple test files directly with `bun test`, always pass `--isolate` or `--parallel`. `--parallel` implies `--isolate`. Without isolation, Bun can share module mocks across files and produce order-dependent failures. Prefer `bun run test` for the full suite because it already isolates test files through `scripts/run-tests.ts`.
+
 ## Versioning
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. Local `build:compile` omits it, so the binary reports `0.0.0-dev`. The CI release workflow injects the real version.

README.md

@@ -50,6 +50,7 @@ Commands:
   completion  [shell]                        Generate shell autocompletion script
   skill                                      Manage the bundled Clerk CLI agent skill
   update      [options]                      Update the Clerk CLI to the latest version
+  deploy                                     Deploy a Clerk application to production
   help        [command]                      Display help for command
 
 Give AI agents better Clerk context: install the Clerk skills

packages/cli-core/src/cli-program.test.ts

@@ -45,6 +45,23 @@ test("users list exposes common filters and pagination options", () => {
   );
 });
 
+test("deploy relies on global options", () => {
+  const program = createProgram();
+  const deploy = program.commands.find((command) => command.name() === "deploy")!;
+  const optionNames = deploy.options.map((option) => option.long);
+
+  expect(optionNames).toEqual([]);
+});
+
+test("deploy status exposes wait option", () => {
+  const program = createProgram();
+  const deploy = program.commands.find((command) => command.name() === "deploy")!;
+  const status = deploy.commands.find((command) => command.name() === "status")!;
+  const optionNames = status.options.map((option) => option.long);
+
+  expect(optionNames).toContain("--wait");
+});
+
 describe("parseIntegerOption (via users list --limit / --offset)", () => {
   function parseUsersList(args: readonly string[]) {
     return createProgram().parseAsync(["users", "list", ...args], { from: "user" });

packages/cli-core/src/cli-program.ts

@@ -37,14 +37,16 @@ import {
   PlapiError,
   FapiError,
   EXIT_CODE,
+  isPromptExitError,
   throwUsageError,
 } from "./lib/errors.ts";
 import { clerkHelpConfig } from "./lib/help.ts";
-import { ExitPromptError } from "@inquirer/core";
 import { isAgent } from "./mode.ts";
 import { log } from "./lib/log.ts";
 import { maybeNotifyUpdate, getCurrentVersion } from "./lib/update-check.ts";
 import { update } from "./commands/update/index.ts";
+import { deploy } from "./commands/deploy/index.ts";
+import { deployStatus } from "./commands/deploy/status-command.ts";
 import { isClerkSkillInstalled } from "./lib/skill-detection.ts";
 import { orgsEnable, orgsDisable } from "./commands/orgs/index.ts";
 import { billingEnable, billingDisable } from "./commands/billing/index.ts";
@@ -119,7 +121,7 @@ Give AI agents better Clerk context: install the Clerk skills
 
   program.hook("preAction", async () => {
     // Reset log level at the start of each command invocation so a previous
-    // --verbose or --debug flag doesn't leak into subsequent runs.
+    // --verbose doesn't leak into subsequent runs.
     setLogLevel("info");
     const opts = program.opts();
     if (opts.verbose) {
@@ -925,6 +927,16 @@ Tutorial — enable completions for your shell:
     ])
     .action(update);
 
+  const deployCmd = program
+    .command("deploy")
+    .description("Deploy a Clerk application to production");
+  deployCmd.command("run", { isDefault: true, hidden: true }).action(deploy);
+  deployCmd
+    .command("status")
+    .description("Show production deploy status (read-only)")
+    .option("--wait", "Wait for DNS, SSL, and email DNS verification with retries")
+    .action(deployStatus);
+
   registerExtras(program);
 
   return program;
@@ -1012,7 +1024,7 @@ export async function runProgram(
   } catch (error) {
     const verbose = program.opts().verbose ?? false;
 
-    if (error instanceof UserAbortError || error instanceof ExitPromptError) {
+    if (error instanceof UserAbortError || isPromptExitError(error)) {
       process.exit(EXIT_CODE.SUCCESS);
     }
 

packages/cli-core/src/commands/auth/login.test.ts

@@ -89,6 +89,7 @@ mock.module("../../lib/autoclaim.ts", () => ({
   attemptAutoclaim: async () => ({ status: "not_keyless" }),
 }));
 
+const { setLogLevel } = await import("../../lib/log.ts");
 const { login } = await import("./login.ts");
 
 describe("login", () => {
@@ -114,6 +115,7 @@ describe("login", () => {
     mockEnsureFirstApplication.mockResolvedValue(undefined);
     mockIsHuman.mockReturnValue(false);
     mockOpenBrowser.mockResolvedValue({ ok: true, launcher: "test" });
+    setLogLevel("info");
     consoleSpy?.mockRestore();
     consoleErrorSpy?.mockRestore();
     try {
@@ -592,6 +594,45 @@ describe("login", () => {
     expect(parsed.searchParams.get("clerk_client")).toBe("cli");
   });
 
+  test("does not emit the OAuth authorize URL through debug logging", async () => {
+    setLogLevel("debug");
+    mockGetValidToken.mockResolvedValue(null);
+    mockBunSpawn();
+
+    const mockServer = {
+      port: 54321,
+      waitForCallback: mock().mockResolvedValue({ code: "fresh-auth-code" }),
+      stop: mock(),
+    };
+    mockStartAuthServer.mockReturnValue(mockServer);
+
+    mockExchangeCodeForToken.mockResolvedValue({
+      access_token: "new-access-token",
+      token_type: "Bearer",
+      expires_in: 3600,
+      refresh_token: "new-refresh-token",
+    });
+    mockCreateOAuthSession.mockReturnValue({
+      accessToken: "new-access-token",
+      refreshToken: "new-refresh-token",
+      expiresAt: 123,
+      tokenType: "Bearer",
+    });
+    mockStoreToken.mockResolvedValue(undefined);
+    mockFetchUserInfo.mockResolvedValue({
+      userId: "user_new",
+      email: "new@example.com",
+    });
+    mockSetAuth.mockResolvedValue(undefined);
+
+    consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+    await runLogin({ showNextSteps: false });
+
+    expect(captured.err).not.toContain("https://test.example.com/oauth/authorize");
+    expect(captured.err).not.toContain("test-state-value");
+    expect(captured.err).not.toContain("test-code-challenge");
+  });
+
   test("calls ensureFirstApplication after a successful OAuth flow", async () => {
     mockGetValidToken.mockResolvedValue(null);
     mockBunSpawn();