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 () => {