feat: add JSON agent output, --json flag, command refactors, and init recipes

src/cli-program.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { setMode, type Mode } from "./mode.js";
+import { setMode, setJsonFlag, type Mode } from "./mode.js";
 import { init } from "./commands/init/index.js";
 import { login } from "./commands/auth/login.js";
 import { logout } from "./commands/auth/logout.js";
@@ -23,11 +23,13 @@ export function createProgram(): Command {
  .name("clerk")
  .description("Clerk CLI")
  .version(require("../package.json").version)
+ .enablePositionalOptions()
  .option(
  "--mode <mode>",
  "Force interaction mode (human or agent). Defaults to auto-detect based on TTY.",
  )
- .option("--verbose", "Show detailed error output");
+ .option("--verbose", "Show detailed error output")
+ .option("--json", "Output structured JSON (same format as agent mode)");
 
  program.hook("preAction", () => {
  const opts = program.opts();
@@ -37,6 +39,9 @@ export function createProgram(): Command {
  }
  setMode(opts.mode as Mode);
  }
+ if (opts.json) {
+ setJsonFlag(true);
+ }
  });
 
  program.command("init").description("Initialize Clerk in your project").action(init);
@@ -80,7 +85,10 @@ export function createProgram(): Command {
  .option("--file <path>", "Target env file (default: auto-detect)")
  .action(pull);
 
- const config = program.command("config").description("Manage instance configuration");
+ const config = program
+ .command("config")
+ .description("Manage instance configuration")
+ .enablePositionalOptions();
 
  config
  .command("pull")

src/commands/api/README.md

@@ -103,7 +103,7 @@ Base URL: `https://api.clerk.com` (overridable via `CLERK_PLATFORM_API_URL`)
 Lists available API endpoints from the Clerk OpenAPI spec.
 
 - Fetches the spec from `clerk/openapi-specs` on GitHub
-- Caches locally in `~/.clerk/cache/` for 24 hours
+- Caches locally in the platform cache directory for 24 hours
 - Supports `--platform` to list Platform API endpoints
 - Optional filter keyword matches against path, summary, tag, and operation ID
 

src/commands/deploy/index.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe, afterEach, mock, spyOn } from "bun:test";
-import { capturedOutput, promptsStubs } from "../../test/stubs.ts";
+import {
+ capturedOutput,
+ configStubs,
+ credentialStoreStubs,
+ promptsStubs,
+} from "../../test/stubs.ts";
 
 const mockIsAgent = mock();
 let _modeOverride: string | undefined;
@@ -9,12 +14,25 @@ mock.module("../../mode.ts", () => ({
  _modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent(...args),
  isHuman: (...args: unknown[]) =>
  _modeOverride !== undefined ? _modeOverride !== "agent" : !mockIsAgent(...args),
+ isJSON: () => (_modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent()),
  setMode: (m: string) => {
  _modeOverride = m;
  },
  getMode: () => _modeOverride ?? "human",
 }));
 
+const mockGetToken = mock();
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: (...args: unknown[]) => mockGetToken(...args),
+}));
+
+const mockResolveProfile = mock();
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+ resolveProfile: (...args: unknown[]) => mockResolveProfile(...args),
+}));
+
 const mockSelect = mock();
 const mockInput = mock();
 const mockConfirm = mock();
@@ -30,12 +48,20 @@ mock.module("@inquirer/prompts", () => ({
 
 const { deploy } = await import("./index.ts");
 
+const mockProfile = {
+ path: "github.com/org/repo",
+ profile: { workspaceId: "", appId: "app_xyz789", instances: { development: "ins_dev" } },
+ resolvedVia: "remote" as const,
+};
+
 describe("deploy", () => {
  let consoleSpy: ReturnType<typeof spyOn>;
 
  afterEach(() => {
  _modeOverride = undefined;
  mockIsAgent.mockReset();
+ mockGetToken.mockReset();
+ mockResolveProfile.mockReset();
  mockSelect.mockReset();
  mockInput.mockReset();
  mockConfirm.mockReset();
@@ -44,56 +70,61 @@ describe("deploy", () => {
  });
 
  describe("agent mode", () => {
- test("outputs deploy prompt and returns", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- expect(consoleSpy).toHaveBeenCalledTimes(1);
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("deploying a Clerk application to production");
- });
-
- test("prompt includes all deployment steps", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("Prerequisites");
- expect(output).toContain("Verify Subscription Compatibility");
- expect(output).toContain("Choose a Production Domain");
- expect(output).toContain("Create the Production Instance");
- expect(output).toContain("Configure Social OAuth Providers");
- expect(output).toContain("Finalize");
- });
-
- test("prompt includes API reference", async () => {
+ test("outputs structured JSON with pre-flight checks", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("/v1/platform/applications");
- expect(output).toContain("instances/production/config");
- expect(output).toContain("instances/development/config");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.command).toBe("deploy");
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: true }),
+ expect.objectContaining({ name: "production_instance", ok: false }),
+ ]),
+ );
  });
 
- test("prompt includes OAuth redirect URI pattern", async () => {
+ test("reports unauthenticated when no token", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue(null);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("accounts.{domain}/v1/oauth_callback");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: false, fix: "clerk auth login" }),
+ ]),
+ );
  });
 
  test("does not trigger interactive prompts", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({ debug: true });
@@ -108,20 +139,29 @@ describe("deploy", () => {
  describe("human mode", () => {
  function mockHumanFlow() {
  mockIsAgent.mockReturnValue(false);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  // Domain selection → OAuth credential choice
  mockSelect.mockResolvedValueOnce("clerk-subdomain").mockResolvedValueOnce("have-credentials");
  mockInput.mockResolvedValueOnce("fake-client-id-12345");
  mockPassword.mockResolvedValueOnce("fake-secret");
  }
 
- test("does not print deploy prompt", async () => {
+ test("does not print JSON on dispose", async () => {
  mockHumanFlow();
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const allOutput = capturedOutput(consoleSpy);
- expect(allOutput).not.toContain("deploying a Clerk application to production");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeUndefined();
  });
 
  test("shows mock banner", async () => {

src/cli-program.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { setMode, type Mode } from "./mode.js";
+import { setMode, setJsonFlag, type Mode } from "./mode.js";
 import { init } from "./commands/init/index.js";
 import { login } from "./commands/auth/login.js";
 import { logout } from "./commands/auth/logout.js";
@@ -23,11 +23,13 @@ export function createProgram(): Command {
  .name("clerk")
  .description("Clerk CLI")
  .version(require("../package.json").version)
+ .enablePositionalOptions()
  .option(
  "--mode <mode>",
  "Force interaction mode (human or agent). Defaults to auto-detect based on TTY.",
  )
- .option("--verbose", "Show detailed error output");
+ .option("--verbose", "Show detailed error output")
+ .option("--json", "Output structured JSON (same format as agent mode)");
 
  program.hook("preAction", () => {
  const opts = program.opts();
@@ -37,6 +39,9 @@ export function createProgram(): Command {
  }
  setMode(opts.mode as Mode);
  }
+ if (opts.json) {
+ setJsonFlag(true);
+ }
  });
 
  program.command("init").description("Initialize Clerk in your project").action(init);
@@ -80,7 +85,10 @@ export function createProgram(): Command {
  .option("--file <path>", "Target env file (default: auto-detect)")
  .action(pull);
 
- const config = program.command("config").description("Manage instance configuration");
+ const config = program
+ .command("config")
+ .description("Manage instance configuration")
+ .enablePositionalOptions();
 
  config
  .command("pull")

src/commands/api/README.md

@@ -103,7 +103,7 @@ Base URL: `https://api.clerk.com` (overridable via `CLERK_PLATFORM_API_URL`)
 Lists available API endpoints from the Clerk OpenAPI spec.
 
 - Fetches the spec from `clerk/openapi-specs` on GitHub
-- Caches locally in `~/.clerk/cache/` for 24 hours
+- Caches locally in the platform cache directory for 24 hours
 - Supports `--platform` to list Platform API endpoints
 - Optional filter keyword matches against path, summary, tag, and operation ID
 

src/commands/deploy/index.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe, afterEach, mock, spyOn } from "bun:test";
-import { capturedOutput, promptsStubs } from "../../test/stubs.ts";
+import {
+ capturedOutput,
+ configStubs,
+ credentialStoreStubs,
+ promptsStubs,
+} from "../../test/stubs.ts";
 
 const mockIsAgent = mock();
 let _modeOverride: string | undefined;
@@ -9,12 +14,25 @@ mock.module("../../mode.ts", () => ({
  _modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent(...args),
  isHuman: (...args: unknown[]) =>
  _modeOverride !== undefined ? _modeOverride !== "agent" : !mockIsAgent(...args),
+ isJSON: () => (_modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent()),
  setMode: (m: string) => {
  _modeOverride = m;
  },
  getMode: () => _modeOverride ?? "human",
 }));
 
+const mockGetToken = mock();
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: (...args: unknown[]) => mockGetToken(...args),
+}));
+
+const mockResolveProfile = mock();
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+ resolveProfile: (...args: unknown[]) => mockResolveProfile(...args),
+}));
+
 const mockSelect = mock();
 const mockInput = mock();
 const mockConfirm = mock();
@@ -30,12 +48,20 @@ mock.module("@inquirer/prompts", () => ({
 
 const { deploy } = await import("./index.ts");
 
+const mockProfile = {
+ path: "github.com/org/repo",
+ profile: { workspaceId: "", appId: "app_xyz789", instances: { development: "ins_dev" } },
+ resolvedVia: "remote" as const,
+};
+
 describe("deploy", () => {
  let consoleSpy: ReturnType<typeof spyOn>;
 
  afterEach(() => {
  _modeOverride = undefined;
  mockIsAgent.mockReset();
+ mockGetToken.mockReset();
+ mockResolveProfile.mockReset();
  mockSelect.mockReset();
  mockInput.mockReset();
  mockConfirm.mockReset();
@@ -44,56 +70,61 @@ describe("deploy", () => {
  });
 
  describe("agent mode", () => {
- test("outputs deploy prompt and returns", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- expect(consoleSpy).toHaveBeenCalledTimes(1);
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("deploying a Clerk application to production");
- });
-
- test("prompt includes all deployment steps", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("Prerequisites");
- expect(output).toContain("Verify Subscription Compatibility");
- expect(output).toContain("Choose a Production Domain");
- expect(output).toContain("Create the Production Instance");
- expect(output).toContain("Configure Social OAuth Providers");
- expect(output).toContain("Finalize");
- });
-
- test("prompt includes API reference", async () => {
+ test("outputs structured JSON with pre-flight checks", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("/v1/platform/applications");
- expect(output).toContain("instances/production/config");
- expect(output).toContain("instances/development/config");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.command).toBe("deploy");
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: true }),
+ expect.objectContaining({ name: "production_instance", ok: false }),
+ ]),
+ );
  });
 
- test("prompt includes OAuth redirect URI pattern", async () => {
+ test("reports unauthenticated when no token", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue(null);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("accounts.{domain}/v1/oauth_callback");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: false, fix: "clerk auth login" }),
+ ]),
+ );
  });
 
  test("does not trigger interactive prompts", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({ debug: true });
@@ -108,20 +139,29 @@ describe("deploy", () => {
  describe("human mode", () => {
  function mockHumanFlow() {
  mockIsAgent.mockReturnValue(false);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  // Domain selection → OAuth credential choice
  mockSelect.mockResolvedValueOnce("clerk-subdomain").mockResolvedValueOnce("have-credentials");
  mockInput.mockResolvedValueOnce("fake-client-id-12345");
  mockPassword.mockResolvedValueOnce("fake-secret");
  }
 
- test("does not print deploy prompt", async () => {
+ test("does not print JSON on dispose", async () => {
  mockHumanFlow();
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const allOutput = capturedOutput(consoleSpy);
- expect(allOutput).not.toContain("deploying a Clerk application to production");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeUndefined();
  });
 
  test("shows mock banner", async () => {

src/cli-program.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { setMode, type Mode } from "./mode.js";
+import { setMode, setJsonFlag, type Mode } from "./mode.js";
 import { init } from "./commands/init/index.js";
 import { login } from "./commands/auth/login.js";
 import { logout } from "./commands/auth/logout.js";
@@ -23,11 +23,13 @@ export function createProgram(): Command {
  .name("clerk")
  .description("Clerk CLI")
  .version(require("../package.json").version)
+ .enablePositionalOptions()
  .option(
  "--mode <mode>",
  "Force interaction mode (human or agent). Defaults to auto-detect based on TTY.",
  )
- .option("--verbose", "Show detailed error output");
+ .option("--verbose", "Show detailed error output")
+ .option("--json", "Output structured JSON (same format as agent mode)");
 
  program.hook("preAction", () => {
  const opts = program.opts();
@@ -37,6 +39,9 @@ export function createProgram(): Command {
  }
  setMode(opts.mode as Mode);
  }
+ if (opts.json) {
+ setJsonFlag(true);
+ }
  });
 
  program.command("init").description("Initialize Clerk in your project").action(init);
@@ -80,7 +85,10 @@ export function createProgram(): Command {
  .option("--file <path>", "Target env file (default: auto-detect)")
  .action(pull);
 
- const config = program.command("config").description("Manage instance configuration");
+ const config = program
+ .command("config")
+ .description("Manage instance configuration")
+ .enablePositionalOptions();
 
  config
  .command("pull")

src/commands/api/README.md

@@ -103,7 +103,7 @@ Base URL: `https://api.clerk.com` (overridable via `CLERK_PLATFORM_API_URL`)
 Lists available API endpoints from the Clerk OpenAPI spec.
 
 - Fetches the spec from `clerk/openapi-specs` on GitHub
-- Caches locally in `~/.clerk/cache/` for 24 hours
+- Caches locally in the platform cache directory for 24 hours
 - Supports `--platform` to list Platform API endpoints
 - Optional filter keyword matches against path, summary, tag, and operation ID
 

src/commands/deploy/index.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe, afterEach, mock, spyOn } from "bun:test";
-import { capturedOutput, promptsStubs } from "../../test/stubs.ts";
+import {
+ capturedOutput,
+ configStubs,
+ credentialStoreStubs,
+ promptsStubs,
+} from "../../test/stubs.ts";
 
 const mockIsAgent = mock();
 let _modeOverride: string | undefined;
@@ -9,12 +14,25 @@ mock.module("../../mode.ts", () => ({
  _modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent(...args),
  isHuman: (...args: unknown[]) =>
  _modeOverride !== undefined ? _modeOverride !== "agent" : !mockIsAgent(...args),
+ isJSON: () => (_modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent()),
  setMode: (m: string) => {
  _modeOverride = m;
  },
  getMode: () => _modeOverride ?? "human",
 }));
 
+const mockGetToken = mock();
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: (...args: unknown[]) => mockGetToken(...args),
+}));
+
+const mockResolveProfile = mock();
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+ resolveProfile: (...args: unknown[]) => mockResolveProfile(...args),
+}));
+
 const mockSelect = mock();
 const mockInput = mock();
 const mockConfirm = mock();
@@ -30,12 +48,20 @@ mock.module("@inquirer/prompts", () => ({
 
 const { deploy } = await import("./index.ts");
 
+const mockProfile = {
+ path: "github.com/org/repo",
+ profile: { workspaceId: "", appId: "app_xyz789", instances: { development: "ins_dev" } },
+ resolvedVia: "remote" as const,
+};
+
 describe("deploy", () => {
  let consoleSpy: ReturnType<typeof spyOn>;
 
  afterEach(() => {
  _modeOverride = undefined;
  mockIsAgent.mockReset();
+ mockGetToken.mockReset();
+ mockResolveProfile.mockReset();
  mockSelect.mockReset();
  mockInput.mockReset();
  mockConfirm.mockReset();
@@ -44,56 +70,61 @@ describe("deploy", () => {
  });
 
  describe("agent mode", () => {
- test("outputs deploy prompt and returns", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- expect(consoleSpy).toHaveBeenCalledTimes(1);
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("deploying a Clerk application to production");
- });
-
- test("prompt includes all deployment steps", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("Prerequisites");
- expect(output).toContain("Verify Subscription Compatibility");
- expect(output).toContain("Choose a Production Domain");
- expect(output).toContain("Create the Production Instance");
- expect(output).toContain("Configure Social OAuth Providers");
- expect(output).toContain("Finalize");
- });
-
- test("prompt includes API reference", async () => {
+ test("outputs structured JSON with pre-flight checks", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("/v1/platform/applications");
- expect(output).toContain("instances/production/config");
- expect(output).toContain("instances/development/config");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.command).toBe("deploy");
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: true }),
+ expect.objectContaining({ name: "production_instance", ok: false }),
+ ]),
+ );
  });
 
- test("prompt includes OAuth redirect URI pattern", async () => {
+ test("reports unauthenticated when no token", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue(null);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("accounts.{domain}/v1/oauth_callback");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: false, fix: "clerk auth login" }),
+ ]),
+ );
  });
 
  test("does not trigger interactive prompts", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({ debug: true });
@@ -108,20 +139,29 @@ describe("deploy", () => {
  describe("human mode", () => {
  function mockHumanFlow() {
  mockIsAgent.mockReturnValue(false);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  // Domain selection → OAuth credential choice
  mockSelect.mockResolvedValueOnce("clerk-subdomain").mockResolvedValueOnce("have-credentials");
  mockInput.mockResolvedValueOnce("fake-client-id-12345");
  mockPassword.mockResolvedValueOnce("fake-secret");
  }
 
- test("does not print deploy prompt", async () => {
+ test("does not print JSON on dispose", async () => {
  mockHumanFlow();
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const allOutput = capturedOutput(consoleSpy);
- expect(allOutput).not.toContain("deploying a Clerk application to production");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeUndefined();
  });
 
  test("shows mock banner", async () => {

src/cli-program.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { setMode, type Mode } from "./mode.js";
+import { setMode, setJsonFlag, type Mode } from "./mode.js";
 import { init } from "./commands/init/index.js";
 import { login } from "./commands/auth/login.js";
 import { logout } from "./commands/auth/logout.js";
@@ -23,11 +23,13 @@ export function createProgram(): Command {
  .name("clerk")
  .description("Clerk CLI")
  .version(require("../package.json").version)
+ .enablePositionalOptions()
  .option(
  "--mode <mode>",
  "Force interaction mode (human or agent). Defaults to auto-detect based on TTY.",
  )
- .option("--verbose", "Show detailed error output");
+ .option("--verbose", "Show detailed error output")
+ .option("--json", "Output structured JSON (same format as agent mode)");
 
  program.hook("preAction", () => {
  const opts = program.opts();
@@ -37,6 +39,9 @@ export function createProgram(): Command {
  }
  setMode(opts.mode as Mode);
  }
+ if (opts.json) {
+ setJsonFlag(true);
+ }
  });
 
  program.command("init").description("Initialize Clerk in your project").action(init);
@@ -80,7 +85,10 @@ export function createProgram(): Command {
  .option("--file <path>", "Target env file (default: auto-detect)")
  .action(pull);
 
- const config = program.command("config").description("Manage instance configuration");
+ const config = program
+ .command("config")
+ .description("Manage instance configuration")
+ .enablePositionalOptions();
 
  config
  .command("pull")

src/commands/api/README.md

@@ -103,7 +103,7 @@ Base URL: `https://api.clerk.com` (overridable via `CLERK_PLATFORM_API_URL`)
 Lists available API endpoints from the Clerk OpenAPI spec.
 
 - Fetches the spec from `clerk/openapi-specs` on GitHub
-- Caches locally in `~/.clerk/cache/` for 24 hours
+- Caches locally in the platform cache directory for 24 hours
 - Supports `--platform` to list Platform API endpoints
 - Optional filter keyword matches against path, summary, tag, and operation ID
 

src/commands/deploy/index.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe, afterEach, mock, spyOn } from "bun:test";
-import { capturedOutput, promptsStubs } from "../../test/stubs.ts";
+import {
+ capturedOutput,
+ configStubs,
+ credentialStoreStubs,
+ promptsStubs,
+} from "../../test/stubs.ts";
 
 const mockIsAgent = mock();
 let _modeOverride: string | undefined;
@@ -9,12 +14,25 @@ mock.module("../../mode.ts", () => ({
  _modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent(...args),
  isHuman: (...args: unknown[]) =>
  _modeOverride !== undefined ? _modeOverride !== "agent" : !mockIsAgent(...args),
+ isJSON: () => (_modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent()),
  setMode: (m: string) => {
  _modeOverride = m;
  },
  getMode: () => _modeOverride ?? "human",
 }));
 
+const mockGetToken = mock();
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: (...args: unknown[]) => mockGetToken(...args),
+}));
+
+const mockResolveProfile = mock();
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+ resolveProfile: (...args: unknown[]) => mockResolveProfile(...args),
+}));
+
 const mockSelect = mock();
 const mockInput = mock();
 const mockConfirm = mock();
@@ -30,12 +48,20 @@ mock.module("@inquirer/prompts", () => ({
 
 const { deploy } = await import("./index.ts");
 
+const mockProfile = {
+ path: "github.com/org/repo",
+ profile: { workspaceId: "", appId: "app_xyz789", instances: { development: "ins_dev" } },
+ resolvedVia: "remote" as const,
+};
+
 describe("deploy", () => {
  let consoleSpy: ReturnType<typeof spyOn>;
 
  afterEach(() => {
  _modeOverride = undefined;
  mockIsAgent.mockReset();
+ mockGetToken.mockReset();
+ mockResolveProfile.mockReset();
  mockSelect.mockReset();
  mockInput.mockReset();
  mockConfirm.mockReset();
@@ -44,56 +70,61 @@ describe("deploy", () => {
  });
 
  describe("agent mode", () => {
- test("outputs deploy prompt and returns", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- expect(consoleSpy).toHaveBeenCalledTimes(1);
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("deploying a Clerk application to production");
- });
-
- test("prompt includes all deployment steps", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("Prerequisites");
- expect(output).toContain("Verify Subscription Compatibility");
- expect(output).toContain("Choose a Production Domain");
- expect(output).toContain("Create the Production Instance");
- expect(output).toContain("Configure Social OAuth Providers");
- expect(output).toContain("Finalize");
- });
-
- test("prompt includes API reference", async () => {
+ test("outputs structured JSON with pre-flight checks", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("/v1/platform/applications");
- expect(output).toContain("instances/production/config");
- expect(output).toContain("instances/development/config");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.command).toBe("deploy");
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: true }),
+ expect.objectContaining({ name: "production_instance", ok: false }),
+ ]),
+ );
  });
 
- test("prompt includes OAuth redirect URI pattern", async () => {
+ test("reports unauthenticated when no token", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue(null);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("accounts.{domain}/v1/oauth_callback");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: false, fix: "clerk auth login" }),
+ ]),
+ );
  });
 
  test("does not trigger interactive prompts", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({ debug: true });
@@ -108,20 +139,29 @@ describe("deploy", () => {
  describe("human mode", () => {
  function mockHumanFlow() {
  mockIsAgent.mockReturnValue(false);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  // Domain selection → OAuth credential choice
  mockSelect.mockResolvedValueOnce("clerk-subdomain").mockResolvedValueOnce("have-credentials");
  mockInput.mockResolvedValueOnce("fake-client-id-12345");
  mockPassword.mockResolvedValueOnce("fake-secret");
  }
 
- test("does not print deploy prompt", async () => {
+ test("does not print JSON on dispose", async () => {
  mockHumanFlow();
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const allOutput = capturedOutput(consoleSpy);
- expect(allOutput).not.toContain("deploying a Clerk application to production");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeUndefined();
  });
 
  test("shows mock banner", async () => {

src/cli-program.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { setMode, type Mode } from "./mode.js";
+import { setMode, setJsonFlag, type Mode } from "./mode.js";
 import { init } from "./commands/init/index.js";
 import { login } from "./commands/auth/login.js";
 import { logout } from "./commands/auth/logout.js";
@@ -23,11 +23,13 @@ export function createProgram(): Command {
  .name("clerk")
  .description("Clerk CLI")
  .version(require("../package.json").version)
+ .enablePositionalOptions()
  .option(
  "--mode <mode>",
  "Force interaction mode (human or agent). Defaults to auto-detect based on TTY.",
  )
- .option("--verbose", "Show detailed error output");
+ .option("--verbose", "Show detailed error output")
+ .option("--json", "Output structured JSON (same format as agent mode)");
 
  program.hook("preAction", () => {
  const opts = program.opts();
@@ -37,6 +39,9 @@ export function createProgram(): Command {
  }
  setMode(opts.mode as Mode);
  }
+ if (opts.json) {
+ setJsonFlag(true);
+ }
  });
 
  program.command("init").description("Initialize Clerk in your project").action(init);
@@ -80,7 +85,10 @@ export function createProgram(): Command {
  .option("--file <path>", "Target env file (default: auto-detect)")
  .action(pull);
 
- const config = program.command("config").description("Manage instance configuration");
+ const config = program
+ .command("config")
+ .description("Manage instance configuration")
+ .enablePositionalOptions();
 
  config
  .command("pull")

src/commands/api/README.md

@@ -103,7 +103,7 @@ Base URL: `https://api.clerk.com` (overridable via `CLERK_PLATFORM_API_URL`)
 Lists available API endpoints from the Clerk OpenAPI spec.
 
 - Fetches the spec from `clerk/openapi-specs` on GitHub
-- Caches locally in `~/.clerk/cache/` for 24 hours
+- Caches locally in the platform cache directory for 24 hours
 - Supports `--platform` to list Platform API endpoints
 - Optional filter keyword matches against path, summary, tag, and operation ID
 

src/commands/deploy/index.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe, afterEach, mock, spyOn } from "bun:test";
-import { capturedOutput, promptsStubs } from "../../test/stubs.ts";
+import {
+ capturedOutput,
+ configStubs,
+ credentialStoreStubs,
+ promptsStubs,
+} from "../../test/stubs.ts";
 
 const mockIsAgent = mock();
 let _modeOverride: string | undefined;
@@ -9,12 +14,25 @@ mock.module("../../mode.ts", () => ({
  _modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent(...args),
  isHuman: (...args: unknown[]) =>
  _modeOverride !== undefined ? _modeOverride !== "agent" : !mockIsAgent(...args),
+ isJSON: () => (_modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent()),
  setMode: (m: string) => {
  _modeOverride = m;
  },
  getMode: () => _modeOverride ?? "human",
 }));
 
+const mockGetToken = mock();
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: (...args: unknown[]) => mockGetToken(...args),
+}));
+
+const mockResolveProfile = mock();
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+ resolveProfile: (...args: unknown[]) => mockResolveProfile(...args),
+}));
+
 const mockSelect = mock();
 const mockInput = mock();
 const mockConfirm = mock();
@@ -30,12 +48,20 @@ mock.module("@inquirer/prompts", () => ({
 
 const { deploy } = await import("./index.ts");
 
+const mockProfile = {
+ path: "github.com/org/repo",
+ profile: { workspaceId: "", appId: "app_xyz789", instances: { development: "ins_dev" } },
+ resolvedVia: "remote" as const,
+};
+
 describe("deploy", () => {
  let consoleSpy: ReturnType<typeof spyOn>;
 
  afterEach(() => {
  _modeOverride = undefined;
  mockIsAgent.mockReset();
+ mockGetToken.mockReset();
+ mockResolveProfile.mockReset();
  mockSelect.mockReset();
  mockInput.mockReset();
  mockConfirm.mockReset();
@@ -44,56 +70,61 @@ describe("deploy", () => {
  });
 
  describe("agent mode", () => {
- test("outputs deploy prompt and returns", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- expect(consoleSpy).toHaveBeenCalledTimes(1);
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("deploying a Clerk application to production");
- });
-
- test("prompt includes all deployment steps", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("Prerequisites");
- expect(output).toContain("Verify Subscription Compatibility");
- expect(output).toContain("Choose a Production Domain");
- expect(output).toContain("Create the Production Instance");
- expect(output).toContain("Configure Social OAuth Providers");
- expect(output).toContain("Finalize");
- });
-
- test("prompt includes API reference", async () => {
+ test("outputs structured JSON with pre-flight checks", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("/v1/platform/applications");
- expect(output).toContain("instances/production/config");
- expect(output).toContain("instances/development/config");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.command).toBe("deploy");
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: true }),
+ expect.objectContaining({ name: "production_instance", ok: false }),
+ ]),
+ );
  });
 
- test("prompt includes OAuth redirect URI pattern", async () => {
+ test("reports unauthenticated when no token", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue(null);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("accounts.{domain}/v1/oauth_callback");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: false, fix: "clerk auth login" }),
+ ]),
+ );
  });
 
  test("does not trigger interactive prompts", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({ debug: true });
@@ -108,20 +139,29 @@ describe("deploy", () => {
  describe("human mode", () => {
  function mockHumanFlow() {
  mockIsAgent.mockReturnValue(false);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  // Domain selection → OAuth credential choice
  mockSelect.mockResolvedValueOnce("clerk-subdomain").mockResolvedValueOnce("have-credentials");
  mockInput.mockResolvedValueOnce("fake-client-id-12345");
  mockPassword.mockResolvedValueOnce("fake-secret");
  }
 
- test("does not print deploy prompt", async () => {
+ test("does not print JSON on dispose", async () => {
  mockHumanFlow();
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const allOutput = capturedOutput(consoleSpy);
- expect(allOutput).not.toContain("deploying a Clerk application to production");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeUndefined();
  });
 
  test("shows mock banner", async () => {

src/cli-program.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { setMode, type Mode } from "./mode.js";
+import { setMode, setJsonFlag, type Mode } from "./mode.js";
 import { init } from "./commands/init/index.js";
 import { login } from "./commands/auth/login.js";
 import { logout } from "./commands/auth/logout.js";
@@ -23,11 +23,13 @@ export function createProgram(): Command {
  .name("clerk")
  .description("Clerk CLI")
  .version(require("../package.json").version)
+ .enablePositionalOptions()
  .option(
  "--mode <mode>",
  "Force interaction mode (human or agent). Defaults to auto-detect based on TTY.",
  )
- .option("--verbose", "Show detailed error output");
+ .option("--verbose", "Show detailed error output")
+ .option("--json", "Output structured JSON (same format as agent mode)");
 
  program.hook("preAction", () => {
  const opts = program.opts();
@@ -37,6 +39,9 @@ export function createProgram(): Command {
  }
  setMode(opts.mode as Mode);
  }
+ if (opts.json) {
+ setJsonFlag(true);
+ }
  });
 
  program.command("init").description("Initialize Clerk in your project").action(init);
@@ -80,7 +85,10 @@ export function createProgram(): Command {
  .option("--file <path>", "Target env file (default: auto-detect)")
  .action(pull);
 
- const config = program.command("config").description("Manage instance configuration");
+ const config = program
+ .command("config")
+ .description("Manage instance configuration")
+ .enablePositionalOptions();
 
  config
  .command("pull")

src/commands/api/README.md

@@ -103,7 +103,7 @@ Base URL: `https://api.clerk.com` (overridable via `CLERK_PLATFORM_API_URL`)
 Lists available API endpoints from the Clerk OpenAPI spec.
 
 - Fetches the spec from `clerk/openapi-specs` on GitHub
-- Caches locally in `~/.clerk/cache/` for 24 hours
+- Caches locally in the platform cache directory for 24 hours
 - Supports `--platform` to list Platform API endpoints
 - Optional filter keyword matches against path, summary, tag, and operation ID
 

src/commands/deploy/index.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe, afterEach, mock, spyOn } from "bun:test";
-import { capturedOutput, promptsStubs } from "../../test/stubs.ts";
+import {
+ capturedOutput,
+ configStubs,
+ credentialStoreStubs,
+ promptsStubs,
+} from "../../test/stubs.ts";
 
 const mockIsAgent = mock();
 let _modeOverride: string | undefined;
@@ -9,12 +14,25 @@ mock.module("../../mode.ts", () => ({
  _modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent(...args),
  isHuman: (...args: unknown[]) =>
  _modeOverride !== undefined ? _modeOverride !== "agent" : !mockIsAgent(...args),
+ isJSON: () => (_modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent()),
  setMode: (m: string) => {
  _modeOverride = m;
  },
  getMode: () => _modeOverride ?? "human",
 }));
 
+const mockGetToken = mock();
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: (...args: unknown[]) => mockGetToken(...args),
+}));
+
+const mockResolveProfile = mock();
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+ resolveProfile: (...args: unknown[]) => mockResolveProfile(...args),
+}));
+
 const mockSelect = mock();
 const mockInput = mock();
 const mockConfirm = mock();
@@ -30,12 +48,20 @@ mock.module("@inquirer/prompts", () => ({
 
 const { deploy } = await import("./index.ts");
 
+const mockProfile = {
+ path: "github.com/org/repo",
+ profile: { workspaceId: "", appId: "app_xyz789", instances: { development: "ins_dev" } },
+ resolvedVia: "remote" as const,
+};
+
 describe("deploy", () => {
  let consoleSpy: ReturnType<typeof spyOn>;
 
  afterEach(() => {
  _modeOverride = undefined;
  mockIsAgent.mockReset();
+ mockGetToken.mockReset();
+ mockResolveProfile.mockReset();
  mockSelect.mockReset();
  mockInput.mockReset();
  mockConfirm.mockReset();
@@ -44,56 +70,61 @@ describe("deploy", () => {
  });
 
  describe("agent mode", () => {
- test("outputs deploy prompt and returns", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- expect(consoleSpy).toHaveBeenCalledTimes(1);
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("deploying a Clerk application to production");
- });
-
- test("prompt includes all deployment steps", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("Prerequisites");
- expect(output).toContain("Verify Subscription Compatibility");
- expect(output).toContain("Choose a Production Domain");
- expect(output).toContain("Create the Production Instance");
- expect(output).toContain("Configure Social OAuth Providers");
- expect(output).toContain("Finalize");
- });
-
- test("prompt includes API reference", async () => {
+ test("outputs structured JSON with pre-flight checks", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("/v1/platform/applications");
- expect(output).toContain("instances/production/config");
- expect(output).toContain("instances/development/config");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.command).toBe("deploy");
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: true }),
+ expect.objectContaining({ name: "production_instance", ok: false }),
+ ]),
+ );
  });
 
- test("prompt includes OAuth redirect URI pattern", async () => {
+ test("reports unauthenticated when no token", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue(null);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("accounts.{domain}/v1/oauth_callback");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: false, fix: "clerk auth login" }),
+ ]),
+ );
  });
 
  test("does not trigger interactive prompts", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({ debug: true });
@@ -108,20 +139,29 @@ describe("deploy", () => {
  describe("human mode", () => {
  function mockHumanFlow() {
  mockIsAgent.mockReturnValue(false);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  // Domain selection → OAuth credential choice
  mockSelect.mockResolvedValueOnce("clerk-subdomain").mockResolvedValueOnce("have-credentials");
  mockInput.mockResolvedValueOnce("fake-client-id-12345");
  mockPassword.mockResolvedValueOnce("fake-secret");
  }
 
- test("does not print deploy prompt", async () => {
+ test("does not print JSON on dispose", async () => {
  mockHumanFlow();
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const allOutput = capturedOutput(consoleSpy);
- expect(allOutput).not.toContain("deploying a Clerk application to production");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeUndefined();
  });
 
  test("shows mock banner", async () => {

src/cli-program.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { setMode, type Mode } from "./mode.js";
+import { setMode, setJsonFlag, type Mode } from "./mode.js";
 import { init } from "./commands/init/index.js";
 import { login } from "./commands/auth/login.js";
 import { logout } from "./commands/auth/logout.js";
@@ -23,11 +23,13 @@ export function createProgram(): Command {
  .name("clerk")
  .description("Clerk CLI")
  .version(require("../package.json").version)
+ .enablePositionalOptions()
  .option(
  "--mode <mode>",
  "Force interaction mode (human or agent). Defaults to auto-detect based on TTY.",
  )
- .option("--verbose", "Show detailed error output");
+ .option("--verbose", "Show detailed error output")
+ .option("--json", "Output structured JSON (same format as agent mode)");
 
  program.hook("preAction", () => {
  const opts = program.opts();
@@ -37,6 +39,9 @@ export function createProgram(): Command {
  }
  setMode(opts.mode as Mode);
  }
+ if (opts.json) {
+ setJsonFlag(true);
+ }
  });
 
  program.command("init").description("Initialize Clerk in your project").action(init);
@@ -80,7 +85,10 @@ export function createProgram(): Command {
  .option("--file <path>", "Target env file (default: auto-detect)")
  .action(pull);
 
- const config = program.command("config").description("Manage instance configuration");
+ const config = program
+ .command("config")
+ .description("Manage instance configuration")
+ .enablePositionalOptions();
 
  config
  .command("pull")

src/commands/api/README.md

@@ -103,7 +103,7 @@ Base URL: `https://api.clerk.com` (overridable via `CLERK_PLATFORM_API_URL`)
 Lists available API endpoints from the Clerk OpenAPI spec.
 
 - Fetches the spec from `clerk/openapi-specs` on GitHub
-- Caches locally in `~/.clerk/cache/` for 24 hours
+- Caches locally in the platform cache directory for 24 hours
 - Supports `--platform` to list Platform API endpoints
 - Optional filter keyword matches against path, summary, tag, and operation ID
 

src/commands/deploy/index.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe, afterEach, mock, spyOn } from "bun:test";
-import { capturedOutput, promptsStubs } from "../../test/stubs.ts";
+import {
+ capturedOutput,
+ configStubs,
+ credentialStoreStubs,
+ promptsStubs,
+} from "../../test/stubs.ts";
 
 const mockIsAgent = mock();
 let _modeOverride: string | undefined;
@@ -9,12 +14,25 @@ mock.module("../../mode.ts", () => ({
  _modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent(...args),
  isHuman: (...args: unknown[]) =>
  _modeOverride !== undefined ? _modeOverride !== "agent" : !mockIsAgent(...args),
+ isJSON: () => (_modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent()),
  setMode: (m: string) => {
  _modeOverride = m;
  },
  getMode: () => _modeOverride ?? "human",
 }));
 
+const mockGetToken = mock();
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: (...args: unknown[]) => mockGetToken(...args),
+}));
+
+const mockResolveProfile = mock();
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+ resolveProfile: (...args: unknown[]) => mockResolveProfile(...args),
+}));
+
 const mockSelect = mock();
 const mockInput = mock();
 const mockConfirm = mock();
@@ -30,12 +48,20 @@ mock.module("@inquirer/prompts", () => ({
 
 const { deploy } = await import("./index.ts");
 
+const mockProfile = {
+ path: "github.com/org/repo",
+ profile: { workspaceId: "", appId: "app_xyz789", instances: { development: "ins_dev" } },
+ resolvedVia: "remote" as const,
+};
+
 describe("deploy", () => {
  let consoleSpy: ReturnType<typeof spyOn>;
 
  afterEach(() => {
  _modeOverride = undefined;
  mockIsAgent.mockReset();
+ mockGetToken.mockReset();
+ mockResolveProfile.mockReset();
  mockSelect.mockReset();
  mockInput.mockReset();
  mockConfirm.mockReset();
@@ -44,56 +70,61 @@ describe("deploy", () => {
  });
 
  describe("agent mode", () => {
- test("outputs deploy prompt and returns", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- expect(consoleSpy).toHaveBeenCalledTimes(1);
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("deploying a Clerk application to production");
- });
-
- test("prompt includes all deployment steps", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("Prerequisites");
- expect(output).toContain("Verify Subscription Compatibility");
- expect(output).toContain("Choose a Production Domain");
- expect(output).toContain("Create the Production Instance");
- expect(output).toContain("Configure Social OAuth Providers");
- expect(output).toContain("Finalize");
- });
-
- test("prompt includes API reference", async () => {
+ test("outputs structured JSON with pre-flight checks", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("/v1/platform/applications");
- expect(output).toContain("instances/production/config");
- expect(output).toContain("instances/development/config");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.command).toBe("deploy");
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: true }),
+ expect.objectContaining({ name: "production_instance", ok: false }),
+ ]),
+ );
  });
 
- test("prompt includes OAuth redirect URI pattern", async () => {
+ test("reports unauthenticated when no token", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue(null);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("accounts.{domain}/v1/oauth_callback");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: false, fix: "clerk auth login" }),
+ ]),
+ );
  });
 
  test("does not trigger interactive prompts", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({ debug: true });
@@ -108,20 +139,29 @@ describe("deploy", () => {
  describe("human mode", () => {
  function mockHumanFlow() {
  mockIsAgent.mockReturnValue(false);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  // Domain selection → OAuth credential choice
  mockSelect.mockResolvedValueOnce("clerk-subdomain").mockResolvedValueOnce("have-credentials");
  mockInput.mockResolvedValueOnce("fake-client-id-12345");
  mockPassword.mockResolvedValueOnce("fake-secret");
  }
 
- test("does not print deploy prompt", async () => {
+ test("does not print JSON on dispose", async () => {
  mockHumanFlow();
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const allOutput = capturedOutput(consoleSpy);
- expect(allOutput).not.toContain("deploying a Clerk application to production");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeUndefined();
  });
 
  test("shows mock banner", async () => {

src/cli-program.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { setMode, type Mode } from "./mode.js";
+import { setMode, setJsonFlag, type Mode } from "./mode.js";
 import { init } from "./commands/init/index.js";
 import { login } from "./commands/auth/login.js";
 import { logout } from "./commands/auth/logout.js";
@@ -23,11 +23,13 @@ export function createProgram(): Command {
  .name("clerk")
  .description("Clerk CLI")
  .version(require("../package.json").version)
+ .enablePositionalOptions()
  .option(
  "--mode <mode>",
  "Force interaction mode (human or agent). Defaults to auto-detect based on TTY.",
  )
- .option("--verbose", "Show detailed error output");
+ .option("--verbose", "Show detailed error output")
+ .option("--json", "Output structured JSON (same format as agent mode)");
 
  program.hook("preAction", () => {
  const opts = program.opts();
@@ -37,6 +39,9 @@ export function createProgram(): Command {
  }
  setMode(opts.mode as Mode);
  }
+ if (opts.json) {
+ setJsonFlag(true);
+ }
  });
 
  program.command("init").description("Initialize Clerk in your project").action(init);
@@ -80,7 +85,10 @@ export function createProgram(): Command {
  .option("--file <path>", "Target env file (default: auto-detect)")
  .action(pull);
 
- const config = program.command("config").description("Manage instance configuration");
+ const config = program
+ .command("config")
+ .description("Manage instance configuration")
+ .enablePositionalOptions();
 
  config
  .command("pull")

src/commands/api/README.md

@@ -103,7 +103,7 @@ Base URL: `https://api.clerk.com` (overridable via `CLERK_PLATFORM_API_URL`)
 Lists available API endpoints from the Clerk OpenAPI spec.
 
 - Fetches the spec from `clerk/openapi-specs` on GitHub
-- Caches locally in `~/.clerk/cache/` for 24 hours
+- Caches locally in the platform cache directory for 24 hours
 - Supports `--platform` to list Platform API endpoints
 - Optional filter keyword matches against path, summary, tag, and operation ID
 

src/commands/deploy/index.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe, afterEach, mock, spyOn } from "bun:test";
-import { capturedOutput, promptsStubs } from "../../test/stubs.ts";
+import {
+ capturedOutput,
+ configStubs,
+ credentialStoreStubs,
+ promptsStubs,
+} from "../../test/stubs.ts";
 
 const mockIsAgent = mock();
 let _modeOverride: string | undefined;
@@ -9,12 +14,25 @@ mock.module("../../mode.ts", () => ({
  _modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent(...args),
  isHuman: (...args: unknown[]) =>
  _modeOverride !== undefined ? _modeOverride !== "agent" : !mockIsAgent(...args),
+ isJSON: () => (_modeOverride !== undefined ? _modeOverride === "agent" : mockIsAgent()),
  setMode: (m: string) => {
  _modeOverride = m;
  },
  getMode: () => _modeOverride ?? "human",
 }));
 
+const mockGetToken = mock();
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: (...args: unknown[]) => mockGetToken(...args),
+}));
+
+const mockResolveProfile = mock();
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+ resolveProfile: (...args: unknown[]) => mockResolveProfile(...args),
+}));
+
 const mockSelect = mock();
 const mockInput = mock();
 const mockConfirm = mock();
@@ -30,12 +48,20 @@ mock.module("@inquirer/prompts", () => ({
 
 const { deploy } = await import("./index.ts");
 
+const mockProfile = {
+ path: "github.com/org/repo",
+ profile: { workspaceId: "", appId: "app_xyz789", instances: { development: "ins_dev" } },
+ resolvedVia: "remote" as const,
+};
+
 describe("deploy", () => {
  let consoleSpy: ReturnType<typeof spyOn>;
 
  afterEach(() => {
  _modeOverride = undefined;
  mockIsAgent.mockReset();
+ mockGetToken.mockReset();
+ mockResolveProfile.mockReset();
  mockSelect.mockReset();
  mockInput.mockReset();
  mockConfirm.mockReset();
@@ -44,56 +70,61 @@ describe("deploy", () => {
  });
 
  describe("agent mode", () => {
- test("outputs deploy prompt and returns", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- expect(consoleSpy).toHaveBeenCalledTimes(1);
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("deploying a Clerk application to production");
- });
-
- test("prompt includes all deployment steps", async () => {
- mockIsAgent.mockReturnValue(true);
- consoleSpy = spyOn(console, "log").mockImplementation(() => {});
-
- await deploy({});
-
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("Prerequisites");
- expect(output).toContain("Verify Subscription Compatibility");
- expect(output).toContain("Choose a Production Domain");
- expect(output).toContain("Create the Production Instance");
- expect(output).toContain("Configure Social OAuth Providers");
- expect(output).toContain("Finalize");
- });
-
- test("prompt includes API reference", async () => {
+ test("outputs structured JSON with pre-flight checks", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("/v1/platform/applications");
- expect(output).toContain("instances/production/config");
- expect(output).toContain("instances/development/config");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.command).toBe("deploy");
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: true }),
+ expect.objectContaining({ name: "production_instance", ok: false }),
+ ]),
+ );
  });
 
- test("prompt includes OAuth redirect URI pattern", async () => {
+ test("reports unauthenticated when no token", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue(null);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const output = consoleSpy.mock.calls[0][0] as string;
- expect(output).toContain("accounts.{domain}/v1/oauth_callback");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeDefined();
+ const parsed = JSON.parse(jsonLine![0] as string);
+ expect(parsed.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ name: "authenticated", ok: false, fix: "clerk auth login" }),
+ ]),
+ );
  });
 
  test("does not trigger interactive prompts", async () => {
  mockIsAgent.mockReturnValue(true);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({ debug: true });
@@ -108,20 +139,29 @@ describe("deploy", () => {
  describe("human mode", () => {
  function mockHumanFlow() {
  mockIsAgent.mockReturnValue(false);
+ mockGetToken.mockResolvedValue("token");
+ mockResolveProfile.mockResolvedValue(mockProfile);
  // Domain selection → OAuth credential choice
  mockSelect.mockResolvedValueOnce("clerk-subdomain").mockResolvedValueOnce("have-credentials");
  mockInput.mockResolvedValueOnce("fake-client-id-12345");
  mockPassword.mockResolvedValueOnce("fake-secret");
  }
 
- test("does not print deploy prompt", async () => {
+ test("does not print JSON on dispose", async () => {
  mockHumanFlow();
  consoleSpy = spyOn(console, "log").mockImplementation(() => {});
 
  await deploy({});
 
- const allOutput = capturedOutput(consoleSpy);
- expect(allOutput).not.toContain("deploying a Clerk application to production");
+ const jsonLine = consoleSpy.mock.calls.find((c: unknown[]) => {
+ try {
+ JSON.parse(c[0] as string);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ expect(jsonLine).toBeUndefined();
  });
 
  test("shows mock banner", async () => {