feat(cli): add the 'clerk webhooks' command group

.changeset/fix-network-request-timeout.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Add a default 60s timeout to all outbound CLI network requests. Previously a stalled connection to a Clerk API could hang a command indefinitely (with no error and no way to recover other than Ctrl-C); requests now abort with a clear, tagged error after 60s. A caller-supplied `AbortSignal` still composes with this default, so tighter per-call budgets continue to win.

.changeset/webhooks.md

@@ -0,0 +1,7 @@
+---
+"clerk": minor
+---
+
+Add the `clerk webhooks` command group for managing webhook endpoints and deliveries from the terminal: `list`, `get`, `create`, `update`, `delete`, `secret [--rotate]`, `event-types`, `messages`, `replay`, `listen`, `trigger`, `verify`, and `open`.
+
+`webhooks listen` supports `--relay-only` to run the local relay tunnel with no Clerk backend (no PLAPI, no auth), and `--token <c_…>` to pin a stable, shareable relay URL. The relay token is persisted per instance, so the relay URL stays the same across restarts.

.claude/rules/command-registration.md

@@ -0,0 +1,68 @@
+---
+description: Command registration conventions — every command group registers via register<Name>(program) from its index.ts, listed in the registrants array
+paths:
+  - "packages/cli-core/src/cli-program.ts"
+  - "packages/cli-core/src/commands/*/index.ts"
+alwaysApply: false
+---
+
+Every command group is wired into the root program through a **registrant function**, never inline in `createProgram()`.
+
+## The pattern
+
+1. Each command group exports `register<Name>(program: Program): void` from `packages/cli-core/src/commands/<name>/index.ts`. It builds the whole `program.command("<name>")` subtree (options, arguments, `.setExamples()`, subcommands) and wires each `.action()` to the handler functions in sibling files.
+2. `cli-program.ts` imports that function and adds it to the `registrants: CommandRegistrant[]` array. `createProgram()` only configures the root program + global hooks, then loops `for (const register of registrants) register(program)`.
+
+**Do not** build a command tree inline inside `createProgram()`. If you're adding a `program.command(...)` (or `webhooks`-style group) directly in `cli-program.ts`, stop — move it to a `register<Name>` in the group's `index.ts` and append the function to `registrants` instead.
+
+## `index.ts` shape
+
+```ts
+import type { Program } from "../../cli-program.ts";
+import { list } from "./list.ts";
+import { create } from "./create.ts";
+
+export function registerApps(program: Program): void {
+  const apps = program.command("apps").description("Manage your Clerk applications");
+
+  apps
+    .command("list")
+    .description("List your Clerk applications")
+    .option("--json", "Output as JSON")
+    .setExamples([{ command: "clerk apps list", description: "List all applications" }])
+    .action(list);
+
+  apps.command("create").argument("<name>", "Application name").action(create);
+}
+```
+
+- Import the `Program` type from `../../cli-program.ts` (type-only — no runtime cycle, this is the established pattern).
+- Keep handler _logic_ in sibling files (`list.ts`, `create.ts`, …); `index.ts` is wiring only. A handler-map object (e.g. `const handlers = { list, create }`) is fine when actions need typed `Parameters<typeof handlers.x>[0]` casts.
+
+## `cli-program.ts` shape
+
+```ts
+import { registerApps } from "./commands/apps/index.ts";
+// …
+const registrants: CommandRegistrant[] = [
+  registerInit,
+  registerApps,
+  // … one entry per command group, in display order …
+  registerExtras,
+];
+
+export function createProgram(): Program {
+  const program = new Command() /* … global options … */ as Program;
+  program.hook("preAction" /* … */);
+  for (const register of registrants) register(program);
+  return program;
+}
+```
+
+Helpers used by only one group (e.g. `createOption`, `parseIntegerOption`, `getAuthToken`) belong in that group's `index.ts`, not imported into `cli-program.ts`.
+
+## Groups with global options, a group-level hook, and subcommands
+
+Build the group exactly as above and attach its concerns inside the same `register<Name>`: parent `.option(...)` flags inherited via `optsWithGlobals()`, a group `webhooks.hook("preAction", …)` for shared gating (e.g. auth), and one `.command(...)` per subcommand. See `commands/webhooks/index.ts` (`registerWebhooks`) for a full multi-subcommand group with inherited `--app`/`--instance`/`--json` options and an auth `preAction`.
+
+Related: [commands.md](./commands.md) (per-command directory + README + agent-mode rules) and [completion.md](./completion.md) (keep `.choices()` / `__complete.ts` in sync when adding commands or options).

.oxlintrc.json

@@ -10,6 +10,7 @@
       "files": [
         "packages/cli-core/src/cli.ts",
         "packages/cli-core/src/cli-program.ts",
+        "packages/cli-core/src/lib/signals.ts",
         "scripts/*"
       ],
       "rules": {

README.md

@@ -41,6 +41,7 @@ Commands:
   open                                       Open Clerk resources in your browser
   apps                                       Manage your Clerk applications
   users       [options]                      Manage Clerk users
+  webhooks    [options]                      Manage webhook endpoints and deliveries
   env                                        Manage environment variables
   config                                     Manage instance configuration
   enable                                     Enable Clerk features on the linked instance

package.json

@@ -8,7 +8,7 @@
     "build": "bun run --filter @clerk/cli-core build",
     "dev": "bun run --cwd packages/cli-core dev",
     "test": "bun test 'packages/cli-core/src/' 'packages/extras/src/' 'scripts/' --parallel --only-failures",
-    "test:e2e": "bun test 'test/e2e/' --retry 1 --parallel --only-failures",
+    "test:e2e": "bun test 'test/e2e/' --retry 1 --parallel=4 --only-failures",
     "test:e2e:op": "bun run scripts/run-e2e-op.ts",
     "e2e:refresh-fixtures": "bun run scripts/refresh-e2e-fixtures.ts",
     "typecheck": "bun run --filter './packages/*' typecheck && tsc --noEmit -p scripts/tsconfig.json && tsc --noEmit -p test/e2e/tsconfig.json",

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

@@ -41,6 +41,7 @@ import { clerkHelpConfig } from "./lib/help.ts";
 import { isAgent } from "./mode.ts";
 import { log } from "./lib/log.ts";
 import { maybeNotifyUpdate, getCurrentVersion } from "./lib/update-check.ts";
+import { registerWebhooks } from "./commands/webhooks/index.ts";
 import { registerExtras } from "@clerk/cli-extras";
 
 /**
@@ -69,6 +70,7 @@ const registrants: CommandRegistrant[] = [
   registerCompletion,
   registerUpdate,
   registerDeploy,
+  registerWebhooks,
   registerExtras,
 ];
 

packages/cli-core/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { createProgram, runProgram } from "./cli-program.ts";
-import { EXIT_CODE } from "./lib/errors.ts";
-process.on("SIGINT", () => process.exit(EXIT_CODE.SIGINT));
+import { cliSigintHandler } from "./lib/signals.ts";
+process.on("SIGINT", cliSigintHandler);
 
 // Fast path for shell completion — intercept before Commander parses
 // to avoid validation errors on partial input from Tab presses.