poc: add schema command to fetch Clerk API specs

CLAUDE.md

@@ -131,7 +131,7 @@ Every CLI command lives in its own directory under `src/commands/<name>/`. Each
 - Clerk API endpoints the command calls (method, path, description)
 - Whether the command (or parts of it) is mocked/stubbed — call this out prominently with a blockquote at the top of the README if so
 
-When adding a new command, create its directory and README. When modifying a command's behavior, options, or API calls, update its README to match.
+When adding a new command, create its directory and README. When modifying a command's behavior, options, or API calls, update its README to match. Always add or update tests (`index.test.ts` in the command directory) when introducing new functionality or changing existing behavior.
 
 When creating or modifying a command, evaluate whether it needs an agent mode. Commands with interactive prompts (menus, wizards, multi-step flows) should check `isAgent()` from `src/mode.ts` and, when in agent mode, output a structured prompt that an AI agent can follow instead of running the interactive flow. Commands that are already non-interactive (e.g., single API calls, browser-based OAuth) typically don't need agent mode.
 

README.md

@@ -31,6 +31,7 @@ Commands:
   api [options] [endpoint] [filter]  Make authenticated requests to the Clerk API
     ls [filter]        List available API endpoints
     (no args)          Interactive request builder (TTY only)
+  schema [options] [api] [path]  Fetch the OpenAPI spec for a Clerk API
   doctor [options]     Check your project's Clerk integration health
   deploy [options]     Deploy your Clerk application (hidden)
 
@@ -84,6 +85,14 @@ clerk api [endpoint] [filter]
 clerk api ls [filter]    List available API endpoints
 clerk api                Interactive request builder (TTY only)
 
+clerk schema [api] [path]
+  [path]               Endpoint path (e.g. /users) or schema type (e.g. User)
+  --spec-version <ver> Spec version (default: latest)
+  --format <format>    Output format: yaml (default) or json
+  --output <file>      Write spec to a file instead of stdout
+  --resolve-refs       Inline $ref references for self-contained output
+  APIs: backend (alias: bapi), frontend (alias: fapi), platform, webhooks
+
 clerk doctor
   --verbose            Show detailed output for each check
   --json               Output results as JSON

src/cli-program.ts

@@ -13,6 +13,7 @@ import { api } from "./commands/api/index.js";
 import { link } from "./commands/link/index.js";
 import { unlink } from "./commands/unlink/index.js";
 import { doctor } from "./commands/doctor/index.js";
+import { schema } from "./commands/schema/index.js";
 import { CliError, UserAbortError, ApiError, EXIT_CODE, throwUsageError } from "./lib/errors.js";
 import { red } from "./lib/color.js";
 
@@ -136,6 +137,17 @@ export function createProgram(): Command {
     .option("--yes", "Skip confirmation for mutating requests")
     .action(api);
 
+  program
+    .command("schema")
+    .description("Fetch the OpenAPI spec for a Clerk API")
+    .argument("[api]", "API name: backend, frontend, platform, or webhooks")
+    .argument("[path]", "Endpoint path (e.g. /users) or schema type (e.g. User)")
+    .option("--spec-version <version>", "Spec version (default: latest)")
+    .option("--format <format>", "Output format: yaml (default) or json")
+    .option("--output <file>", "Write spec to a file instead of stdout")
+    .option("--resolve-refs", "Inline $ref references for self-contained output")
+    .action(schema);
+
   program
     .command("doctor")
     .description("Check your project's Clerk integration health")

src/commands/schema/README.md

@@ -0,0 +1,64 @@
+# `clerk schema`
+
+Fetch and output the OpenAPI specification for Clerk APIs. Supports full-spec output, path-based introspection, type lookups, and `$ref` resolution.
+
+## Usage
+
+```
+clerk schema                                     # List available APIs and versions
+clerk schema backend                             # Backend API (latest, YAML)
+clerk schema frontend                            # Frontend API (latest, YAML)
+clerk schema platform                            # Platform API (latest, YAML)
+clerk schema webhooks                            # Webhooks spec (latest, YAML)
+clerk schema backend /users                      # Just the /users endpoint
+clerk schema backend User                        # Just the User schema type
+clerk schema backend /users --resolve-refs       # Endpoint with all $refs inlined
+clerk schema backend User --resolve-refs         # Type with all $refs inlined
+clerk schema backend --format json               # Full spec as JSON
+clerk schema backend --spec-version 2024-10-01   # Specific version
+clerk schema platform --output spec.yml          # Write to file
+```
+
+## Options
+
+| Option                 | Description                                         |
+| ---------------------- | --------------------------------------------------- |
+| `[path]`               | Endpoint path (e.g. `/users`) or type (e.g. `User`) |
+| `--spec-version <ver>` | Spec version (default: latest for the API)          |
+| `--format <fmt>`       | Output format: `yaml` (default) or `json`           |
+| `--output <file>`      | Write spec to a file instead of stdout              |
+| `--resolve-refs`       | Inline `$ref` references for self-contained output  |
+
+## Path introspection
+
+When a second argument is provided, the command extracts just the matching portion of the spec:
+
+- **Endpoint paths** start with `/` — e.g. `clerk schema backend /users` looks up the `/users` endpoint. Automatically tries `/v1` and `/v2` prefixes if an exact match isn't found.
+- **Schema types** don't start with `/` — e.g. `clerk schema backend User` looks up the `User` schema in `components.schemas`. Case-insensitive matching is supported.
+
+If no match is found, the command suggests similar paths or types.
+
+## `--resolve-refs`
+
+Inlines all `$ref` references so the output is fully self-contained. Circular references are detected and marked with a `$comment: "circular reference"` annotation instead of causing infinite expansion.
+
+This is especially useful for AI agents that need a complete type definition without chasing references.
+
+## APIs
+
+| Name       | Aliases | Latest version | All versions                                               |
+| ---------- | ------- | -------------- | ---------------------------------------------------------- |
+| `backend`  | `bapi`  | `2025-11-10`   | 2021-02-05, 2024-10-01, 2025-03-12, 2025-04-10, 2025-11-10 |
+| `frontend` | `fapi`  | `2025-11-10`   | 2021-02-05, 2024-10-01, 2025-03-12, 2025-04-10, 2025-11-10 |
+| `platform` |         | `beta`         | beta                                                       |
+| `webhooks` |         | `2025-04-15`   | 2025-04-15                                                 |
+
+Specs are fetched from https://github.com/clerk/openapi-specs.
+
+## Caching
+
+Specs are cached locally for 24 hours to avoid repeated network requests. Cache is stored in the CLI's standard cache directory.
+
+## No authentication required
+
+This command fetches publicly available specs from GitHub and does not require authentication.