@brew.new/cli 0.9.0 → 0.10.0

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createInterface } from 'readline/promises';
+import { BrewApiError, BrewConnectionError, BrewTimeoutError, createBrewClient, GENERATE_IMAGE_DEFAULT_TIMEOUT_MS, GIF_DEFAULT_TIMEOUT_MS, AUDIT_EMAIL_DEFAULT_TIMEOUT_MS, EDIT_EMAIL_DEFAULT_TIMEOUT_MS, GENERATE_EMAIL_DEFAULT_TIMEOUT_MS, IMPORT_EMAIL_DEFAULT_TIMEOUT_MS, IMPORT_FIGMA_DEFAULT_TIMEOUT_MS, PREVIEW_EMAIL_CLIENTS_DEFAULT_TIMEOUT_MS } from '@brew.new/sdk';
 import { CommanderError, Command } from 'commander';
-import { BrewApiError, createBrewClient, AUDIT_EMAIL_DEFAULT_TIMEOUT_MS } from '@brew.new/sdk';
 import { readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
@@ -12,6 +12,35 @@ var EXIT_RUNTIME = 1;
 var EXIT_USAGE = 2;
 var EXIT_AUTH = 3;
 var EXIT_CONFIRM = 4;
+var EXIT_INTERRUPTED = 130;
+var EXIT_TERMINATED = 143;
+function exitCodeForSignal(signal) {
+  return signal === "SIGINT" ? EXIT_INTERRUPTED : EXIT_TERMINATED;
+}
+var CliInterruptError = class extends Error {
+  signal;
+  constructor(signal) {
+    super(signal === "SIGINT" ? "Interrupted." : "Terminated.");
+    this.name = "CliInterruptError";
+    this.signal = signal;
+  }
+};
+var CliTimeoutError = class extends Error {
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`No complete response within ${timeoutMs}ms.`);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var CliConnectionError = class extends Error {
+  constructor(cause) {
+    super("The connection failed before a complete response arrived.", {
+      cause
+    });
+    this.name = "CliConnectionError";
+  }
+};
 var CliUsageError = class extends Error {
 };
 var CliAuthError = class extends Error {
@@ -88,6 +117,9 @@ var ConfirmationRequiredError = class extends Error {
   }
 };
 function toExitCode(error) {
+  if (error instanceof CliInterruptError) {
+    return exitCodeForSignal(error.signal);
+  }
   if (error instanceof ConfirmationRequiredError) {
     return EXIT_CONFIRM;
   }
@@ -103,7 +135,40 @@ function toExitCode(error) {
   }
   return EXIT_RUNTIME;
 }
-function toErrorEnvelope(error) {
+function toErrorEnvelope(error, context = {}) {
+  const envelope = baseEnvelope(error, context);
+  const drain = context.drain;
+  return withReplayAdvice(
+    drain === void 0 ? envelope : { ...envelope, progress: drain },
+    error,
+    context
+  );
+}
+function baseEnvelope(error, context) {
+  if (error instanceof CliInterruptError) {
+    return {
+      code: "CLI_INTERRUPTED",
+      type: "cancelled",
+      message: `${error.signal === "SIGINT" ? "Interrupted" : "Terminated"} (${error.signal}) ${context.request === void 0 ? "before any request was sent." : `while waiting for ${context.request.method} ${pathOnly(context.request.path)}.`}`
+    };
+  }
+  if (isTimeoutError(error)) {
+    return {
+      code: "CLI_TIMEOUT",
+      type: "service_unavailable",
+      message: timeoutMessage(error, context),
+      suggestion: "Retry the request. Reuse the same Idempotency-Key for a POST request."
+    };
+  }
+  if (error instanceof BrewConnectionError || error instanceof CliConnectionError) {
+    const cause = error.cause instanceof Error && error.cause.message !== "" ? `: ${error.cause.message}` : "";
+    return {
+      code: "CLI_CONNECTION",
+      type: "service_unavailable",
+      message: error instanceof BrewConnectionError ? error.message : `${error.message.replace(/\.$/, "")}${context.request === void 0 ? "" : ` (${context.request.method} ${pathOnly(context.request.path)})`}${cause}.`,
+      suggestion: "Check the connection and retry the request."
+    };
+  }
   if (error instanceof BrewApiError || error instanceof CliApiError) {
     const details = readErrorDetails(error);
     return {
@@ -133,14 +198,6 @@ function toErrorEnvelope(error) {
       message: error.message
     };
   }
-  if (isTimeoutError(error)) {
-    return {
-      code: "CLI_TIMEOUT",
-      type: "service_unavailable",
-      message: "The request timed out before the API responded.",
-      suggestion: "Retry the request. Reuse the same Idempotency-Key for a POST request."
-    };
-  }
   if (error instanceof CommandAbortedError) {
     return {
       code: "CLI_ABORTED",
@@ -155,7 +212,60 @@ function toErrorEnvelope(error) {
   }
   return { code: "CLI_UNEXPECTED", type: "internal_error", message };
 }
-function printError(ctx, error) {
+var IN_PROGRESS_CODE = "IDEMPOTENCY_IN_PROGRESS";
+function withReplayAdvice(envelope, error, context) {
+  if (!isUnknownOutcome(envelope)) {
+    return envelope;
+  }
+  const isInProgress = envelope.code === IN_PROGRESS_CODE || error instanceof BrewTimeoutError && error.inProgress || error instanceof BrewConnectionError && error.inProgress;
+  const holdNote = isInProgress ? " The first attempt is still running on the server, which holds its key for up to 15 minutes: until then a replay answers 409 IDEMPOTENCY_IN_PROGRESS, so wait and re-run." : "";
+  if (context.request === void 0) {
+    return envelope.code === "CLI_INTERRUPTED" ? { ...envelope, suggestion: "Nothing was sent." } : envelope;
+  }
+  if (context.isRead === true || context.request.method === "GET") {
+    return envelope.code === "CLI_INTERRUPTED" ? { ...envelope, suggestion: "It only reads; nothing was changed." } : envelope;
+  }
+  const key = errorIdempotencyKey(error) ?? context.request.idempotencyKey;
+  if (context.replays !== true || key === void 0) {
+    return {
+      ...envelope,
+      suggestion: `${pathOnly(context.request.path)} may already have been changed, and this route does not replay a request: check its current state before running it again.`
+    };
+  }
+  const retryCommand = context.retryCommand?.(key);
+  return {
+    ...envelope,
+    suggestion: `The API keeps working after the CLI disconnects, so this may still complete. Re-run with --idempotency-key ${key} to get its result instead of running it twice (the key replays for 24 hours${context.readsStdin === true ? "; pipe the same input to it again" : ""}).${holdNote}`,
+    idempotencyKey: key,
+    ...retryCommand === void 0 ? {} : { retryCommand }
+  };
+}
+function isUnknownOutcome(envelope) {
+  if (envelope.code === "CLI_INTERRUPTED" || envelope.code === "CLI_TIMEOUT" || envelope.code === "CLI_CONNECTION" || envelope.code === IN_PROGRESS_CODE) {
+    return true;
+  }
+  return envelope.status !== void 0 && envelope.status >= 500;
+}
+function errorIdempotencyKey(error) {
+  if (error instanceof BrewApiError || error instanceof BrewTimeoutError || error instanceof BrewConnectionError) {
+    return error.idempotencyKey;
+  }
+  return void 0;
+}
+function timeoutMessage(error, context) {
+  if (error instanceof BrewTimeoutError) {
+    return error.message;
+  }
+  if (error instanceof CliTimeoutError) {
+    const request = context.request;
+    return request === void 0 ? error.message : `${error.message.replace(/\.$/, "")} (${request.method} ${pathOnly(request.path)}).`;
+  }
+  return "The request timed out before the API responded.";
+}
+function pathOnly(path) {
+  return path.split("?")[0] ?? path;
+}
+function printError(ctx, error, context = {}) {
   if (error instanceof ConfirmationRequiredError) {
     ctx.io.stdout.write(`${JSON.stringify(error.envelope)}
 `);
@@ -168,7 +278,7 @@ function printError(ctx, error) {
     }
     return;
   }
-  const envelope = toErrorEnvelope(error);
+  const envelope = toErrorEnvelope(error, context);
   if (ctx.mode === "json") {
     ctx.io.stderr.write(`${JSON.stringify({ error: envelope })}
 `);
@@ -181,6 +291,15 @@ function printError(ctx, error) {
   if (envelope.suggestion) {
     lines.push(envelope.suggestion);
   }
+  if (envelope.retryCommand) {
+    lines.push(`Re-run: ${envelope.retryCommand}`);
+  }
+  if (envelope.progress) {
+    const { rowsFetched, pagesFetched, resumeCursor } = envelope.progress;
+    lines.push(
+      `Fetched ${rowsFetched} rows in ${pagesFetched} pages before stopping${resumeCursor === void 0 ? "." : `; resume with --cursor ${resumeCursor} --all.`}`
+    );
+  }
   if (envelope.docs) {
     lines.push(`Docs: ${envelope.docs}`);
   }
@@ -219,7 +338,7 @@ function apiErrorStatus(error) {
   }
 }
 function isTimeoutError(error) {
-  return typeof error === "object" && error !== null && "name" in error && error.name === "TimeoutError";
+  return error instanceof BrewTimeoutError || typeof error === "object" && error !== null && "name" in error && error.name === "TimeoutError";
 }
 
 // src/lib/confirm.ts
@@ -255,22 +374,58 @@ Proceed? [y/N] `);
   });
 }
 function buildConfirmCommand(rawArgv) {
+  return ["brew-cli", ...rerunTokens(rawArgv), "--yes"].join(" ");
+}
+function buildRetryCommand(rawArgv, idempotencyKey) {
+  return [
+    "brew-cli",
+    ...rerunTokens(rawArgv, { dropIdempotencyKey: true }),
+    "--idempotency-key",
+    shellQuote(idempotencyKey)
+  ].join(" ");
+}
+function rerunTokens(rawArgv, options = {}) {
   const tokens = [];
   for (let index = 0; index < rawArgv.length; index += 1) {
     const token = rawArgv[index];
     if (token === void 0) {
       continue;
     }
-    if (token === "--api-key") {
+    if (token === "--api-key" || options.dropIdempotencyKey === true && token === "--idempotency-key") {
       index += 1;
       continue;
     }
-    if (token.startsWith("--api-key=")) {
+    if (token.startsWith("--api-key=") || options.dropIdempotencyKey === true && token.startsWith("--idempotency-key=")) {
+      continue;
+    }
+    if (token.startsWith("--header=")) {
+      if (!isCredentialHeader(token.slice("--header=".length))) {
+        tokens.push(shellQuote(token));
+      }
+      continue;
+    }
+    if (token === "--header") {
+      const values = [];
+      while (index + 1 < rawArgv.length && !(rawArgv[index + 1] ?? "").startsWith("-")) {
+        index += 1;
+        const value = rawArgv[index] ?? "";
+        if (!isCredentialHeader(value)) {
+          values.push(shellQuote(value));
+        }
+      }
+      if (values.length > 0) {
+        tokens.push("--header", ...values);
+      }
       continue;
     }
     tokens.push(shellQuote(token));
   }
-  return ["brew-cli", ...tokens, "--yes"].join(" ");
+  return tokens;
+}
+var CREDENTIAL_HEADER_NAME = /authorization|cookie|api-?key|auth|token|secret|passw(or)?d|session|signature|credential/i;
+function isCredentialHeader(header) {
+  const name = /^\s*([^:\s]+)\s*:/.exec(header)?.[1];
+  return name !== void 0 && CREDENTIAL_HEADER_NAME.test(name);
 }
 function shellQuote(token) {
   if (/^[A-Za-z0-9@%+=:,./_-]+$/.test(token)) {
@@ -281,7 +436,7 @@ function shellQuote(token) {
 
 // src/version.ts
 var CLI_NAME = "brew-cli";
-var CLI_VERSION = "0.9.0" ;
+var CLI_VERSION = "0.10.0" ;
 var CONFIG_KEYS = ["apiKey", "brandId", "apiUrl"];
 function isConfigKey(value) {
   return CONFIG_KEYS.includes(value);
@@ -384,12 +539,18 @@ function resolveAuth(input) {
   const apiKeySource = keyFromFlag ? "flag" : keyFromEnv ? "env" : "config";
   return { apiKey, apiKeySource, brandId, apiUrl };
 }
-function buildSdkClient(auth) {
+function buildSdkClient(auth, transport) {
   return createBrewClient({
     apiKey: auth.apiKey,
     baseUrl: auth.apiUrl,
     userAgent: `${CLI_NAME}/${CLI_VERSION}`,
-    ...auth.brandId === void 0 ? {} : { brandId: auth.brandId }
+    ...auth.brandId === void 0 ? {} : { brandId: auth.brandId },
+    // Client-wide, so every call the command makes observes the interrupt
+    // and the deadline without each command file threading a signal.
+    signal: transport.signal,
+    fetch: transport.fetch,
+    ...transport.timeoutMs === void 0 ? {} : { timeoutMs: transport.timeoutMs },
+    ...transport.maxRetries === void 0 ? {} : { maxRetries: transport.maxRetries }
   });
 }
 function isOrgLevelPath(url) {
@@ -466,6 +627,114 @@ function formatCell(value) {
   return String(value);
 }
 
+// src/lib/transport.ts
+function apiPathOf(url) {
+  const index = url.pathname.indexOf("/v1/");
+  const path = index === -1 ? url.pathname : url.pathname.slice(index);
+  return `${path}${url.search}`;
+}
+function createTransportState() {
+  let lastRequest;
+  let attempts = 0;
+  let drain;
+  return {
+    lastRequest: () => lastRequest,
+    attempts: () => attempts,
+    record: (request) => {
+      lastRequest = request;
+      attempts += 1;
+    },
+    drain: () => drain,
+    setDrain: (progress2) => {
+      drain = progress2;
+    }
+  };
+}
+function recordingFetch(state) {
+  return (input, init) => {
+    if (init?.signal?.aborted === true) {
+      return globalThis.fetch(input, init);
+    }
+    const url = new URL(
+      typeof input === "string" || input instanceof URL ? input : input.url
+    );
+    state.record({
+      method: (init?.method ?? "GET").toUpperCase(),
+      path: apiPathOf(url),
+      idempotencyKey: new Headers(init?.headers).get("idempotency-key") ?? void 0
+    });
+    return globalThis.fetch(input, init);
+  };
+}
+function anySignal(signals) {
+  const present = signals.filter(
+    (signal) => signal !== void 0
+  );
+  const [only, ...rest] = present;
+  if (only !== void 0 && rest.length === 0) {
+    return { signal: only, release: () => void 0 };
+  }
+  if (typeof AbortSignal.any === "function") {
+    return { signal: AbortSignal.any(present), release: () => void 0 };
+  }
+  const controller = new AbortController();
+  const alreadyAborted = present.find((signal) => signal.aborted);
+  if (alreadyAborted !== void 0) {
+    controller.abort(alreadyAborted.reason);
+    return { signal: controller.signal, release: () => void 0 };
+  }
+  const listeners = present.map((source) => {
+    const onAbort = () => {
+      controller.abort(source.reason);
+    };
+    source.addEventListener("abort", onAbort, { once: true });
+    return { source, onAbort };
+  });
+  return {
+    signal: controller.signal,
+    release: () => {
+      for (const { source, onAbort } of listeners) {
+        source.removeEventListener("abort", onAbort);
+      }
+    }
+  };
+}
+var DURATION = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/;
+var UNIT_MS = { ms: 1, s: 1e3, m: 6e4, h: 36e5 };
+var MAX_TIMEOUT_MS = 24 * 36e5;
+function parseTimeoutFlag(value) {
+  if (value === void 0) {
+    return;
+  }
+  const match = typeof value === "string" ? DURATION.exec(value.trim()) : null;
+  const unit = match?.[2] ?? "s";
+  const ms = match === null ? Number.NaN : Math.round(Number(match[1]) * UNIT_MS[unit]);
+  if (!(ms >= 1 && ms <= MAX_TIMEOUT_MS)) {
+    throw new CliUsageError(
+      `--timeout takes a positive duration up to 24h: 90, 90s, 1500ms or 5m (a bare number is seconds); got "${String(value)}".`
+    );
+  }
+  return ms;
+}
+function parseMaxRetriesFlag(value) {
+  if (value === void 0) {
+    return;
+  }
+  const parsed = typeof value === "string" && value.trim() !== "" ? Number(value) : Number.NaN;
+  if (!(Number.isInteger(parsed) && parsed >= 0 && parsed <= 10)) {
+    throw new CliUsageError(
+      `--max-retries takes a whole number from 0 to 10; got "${String(value)}".`
+    );
+  }
+  return parsed;
+}
+function resolveBudget(input) {
+  if (input.timeoutMs !== void 0) {
+    return { deadlineMs: input.timeoutMs, attemptMs: input.timeoutMs };
+  }
+  return { deadlineMs: input.defaultTimeoutMs, attemptMs: void 0 };
+}
+
 // src/lib/context.ts
 function makeContext(input) {
   const globals = readGlobalFlags(input.flags);
@@ -473,12 +742,38 @@ function makeContext(input) {
     isJsonFlag: globals.json,
     isTtyOut: input.io.isTtyOut
   });
+  const budget = resolveBudget({
+    timeoutMs: globals.timeoutMs,
+    defaultTimeoutMs: input.traits?.defaultTimeoutMs
+  });
+  const deadline = new AbortController();
+  let deadlineTimer;
+  const { signal } = anySignal([input.io.signal, deadline.signal]);
+  const transport = createTransportState();
   const cache = /* @__PURE__ */ new Map();
-  return {
+  const ctx = {
     io: input.io,
     mode,
     globals,
     rawArgv: input.rawArgv,
+    signal,
+    budget,
+    transport,
+    traits: input.traits,
+    startDeadline: () => {
+      const ms = budget.deadlineMs;
+      if (ms === void 0 || deadlineTimer !== void 0) {
+        return;
+      }
+      deadlineTimer = setTimeout(() => {
+        deadline.abort(new CliTimeoutError(ms));
+      }, ms);
+    },
+    stopDeadline: () => {
+      if (deadlineTimer !== void 0) {
+        clearTimeout(deadlineTimer);
+      }
+    },
     client: (options) => {
       const key = options?.allowAnonymous === true ? "anonymous" : "authed";
       const existing = cache.get(key);
@@ -490,11 +785,20 @@ function makeContext(input) {
         env: input.io.env,
         allowAnonymous: options?.allowAnonymous === true
       });
-      const client = buildSdkClient(auth);
+      const client = buildSdkClient(auth, sdkTransportFor(ctx));
       cache.set(key, client);
       return client;
     }
   };
+  return ctx;
+}
+function sdkTransportFor(ctx) {
+  return {
+    signal: ctx.signal,
+    fetch: recordingFetch(ctx.transport),
+    timeoutMs: ctx.budget.attemptMs,
+    maxRetries: ctx.globals.maxRetries
+  };
 }
 function makeFallbackContext(io, rawArgv) {
   const flags = {
@@ -510,7 +814,9 @@ function readGlobalFlags(flags) {
     yes: flags.yes === true,
     apiKey: readStringFlag(flags.apiKey),
     brand: readStringFlag(flags.brand),
-    apiUrl: readStringFlag(flags.apiUrl)
+    apiUrl: readStringFlag(flags.apiUrl),
+    timeoutMs: parseTimeoutFlag(flags.timeout),
+    maxRetries: parseMaxRetriesFlag(flags.maxRetries)
   };
 }
 function readStringFlag(value) {
@@ -542,6 +848,14 @@ var GLOBAL_FLAGS = [
   {
     flag: "--api-url <url>",
     summary: "API base URL (else BREW_API_URL, else https://brew.new/api)"
+  },
+  {
+    flag: "--timeout <duration>",
+    summary: "Give up after this long, retries and the response body included (90s, 1500ms, 5m)"
+  },
+  {
+    flag: "--max-retries <n>",
+    summary: "Retries after a transient failure, 0-10 (default 2; raw requests make one attempt)"
   }
 ];
 function asSdkInput(value) {
@@ -661,6 +975,61 @@ var INPUT_FLAG = {
   flag: "--input <json>",
   summary: "Full JSON request body, or - to read stdin (flags override it)"
 };
+var LONG_RUNNING_ROUTES = [
+  {
+    method: "POST",
+    path: "/v1/emails",
+    timeoutMs: GENERATE_EMAIL_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "PATCH",
+    path: "/v1/emails/{emailId}",
+    timeoutMs: EDIT_EMAIL_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/emails/audit",
+    timeoutMs: AUDIT_EMAIL_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/emails/{emailId}/client-previews",
+    timeoutMs: PREVIEW_EMAIL_CLIENTS_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/emails/import",
+    timeoutMs: IMPORT_EMAIL_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/emails/figma",
+    timeoutMs: IMPORT_FIGMA_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/content/gif",
+    timeoutMs: GIF_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/content/generate-image",
+    timeoutMs: GENERATE_IMAGE_DEFAULT_TIMEOUT_MS
+  }
+];
+function longRunningTimeoutMs(input) {
+  const bare = input.path.split("?")[0] ?? input.path;
+  return LONG_RUNNING_ROUTES.find(
+    (route) => route.method === input.method && matchesTemplate(route.path, bare)
+  )?.timeoutMs;
+}
+function matchesTemplate(template, path) {
+  const want = template.split("/");
+  const have = path.split("/");
+  return want.length === have.length && want.every(
+    (segment, index) => segment.startsWith("{") && segment.endsWith("}") ? (have[index] ?? "") !== "" : segment === have[index]
+  );
+}
 
 // src/lib/paginate.ts
 async function collectAll(ctx, fetchPage) {
@@ -668,7 +1037,20 @@ async function collectAll(ctx, fetchPage) {
   let cursor;
   let pageCount = 0;
   for (; ; ) {
-    const page = await fetchPage(cursor);
+    let page;
+    try {
+      ctx.signal.throwIfAborted();
+      page = await fetchPage(cursor);
+    } catch (error) {
+      if (pageCount > 0) {
+        ctx.transport.setDrain({
+          rowsFetched: rows.length,
+          pagesFetched: pageCount,
+          ...cursor === void 0 ? {} : { resumeCursor: cursor }
+        });
+      }
+      throw error;
+    }
     rows.push(...page.data);
     pageCount += 1;
     const next = page.pagination?.cursor ?? null;
@@ -861,116 +1243,15 @@ var analyticsCampaignsCommand = defineCommand({
   }
 });
 
-// src/lib/raw-request.ts
-async function rawRequest(ctx, request) {
-  const auth = resolveAuth({
-    globals: ctx.globals,
-    env: ctx.io.env,
-    ...request.allowAnonymous === true ? { allowAnonymous: true } : {}
-  });
-  const hasBody = request.body !== void 0;
-  const idempotencyKey = resolveRawIdempotencyKey(
-    request.method,
-    request.idempotencyKey
-  );
-  const headers = buildRawHeaders({
-    auth,
-    path: request.path,
-    hasJsonBody: hasBody,
-    idempotencyKey
-  });
-  const url = new URL(`${auth.apiUrl}${request.path}`);
-  for (const [key, value] of Object.entries(request.query ?? {})) {
-    if (value !== void 0) {
-      url.searchParams.set(key, value);
-    }
-  }
-  const response = await fetch(url, {
-    method: request.method,
-    headers,
-    ...hasBody ? { body: JSON.stringify(request.body) } : {},
-    ...request.signal === void 0 ? {} : { signal: request.signal }
-  });
-  const text = await response.text();
-  const parsed = tryParseJson(text);
-  if (!response.ok) {
-    throw responseToApiError(response, parsed);
-  }
-  if (parsed === void 0) {
-    throw new CliApiError({
-      status: response.status,
-      code: "UNEXPECTED_RESPONSE",
-      type: "internal_error",
-      message: "The API returned a non-JSON success response."
-    });
-  }
-  return parsed;
-}
-function resolveRawIdempotencyKey(method, provided) {
-  if (provided !== void 0 && provided !== "") {
-    return provided;
-  }
-  return method === "POST" ? crypto.randomUUID() : void 0;
-}
-function buildRawHeaders(input) {
-  const headers = new Headers({
-    authorization: `Bearer ${input.auth.apiKey}`,
-    "user-agent": `${CLI_NAME}/${CLI_VERSION}`,
-    accept: "application/json, text/plain;q=0.9"
-  });
-  if (input.hasJsonBody) {
-    headers.set("content-type", "application/json");
-  }
-  if (input.auth.brandId !== void 0 && !isOrgLevelPath(input.path)) {
-    headers.set("x-brand-id", input.auth.brandId);
-  }
-  if (input.idempotencyKey !== void 0 && input.idempotencyKey !== "") {
-    headers.set("idempotency-key", input.idempotencyKey);
-  }
-  return headers;
-}
-function responseToApiError(response, parsed) {
-  const requestId = response.headers.get("x-request-id") ?? void 0;
-  const record = isRecord2(parsed) ? parsed : void 0;
-  const standard = record !== void 0 && isRecord2(record.error) ? record.error : void 0;
-  const envelope = standard ?? record;
-  const readField = (key) => {
-    const value = envelope?.[key];
-    return typeof value === "string" ? value : void 0;
-  };
-  const param = readField("param");
-  const suggestion = readField("suggestion") ?? (envelope === void 0 ? void 0 : suggestionForStatus(response.status));
-  const docs = readField("docs");
-  const details = isRecord2(envelope?.details) ? envelope.details : void 0;
-  return new CliApiError({
-    status: response.status,
-    code: readField("code") ?? "HTTP_ERROR",
-    type: readField("type") ?? errorTypeForStatus(response.status),
-    message: readField("message") ?? `Request failed with status ${response.status}`,
-    ...param === void 0 ? {} : { param },
-    ...suggestion === void 0 ? {} : { suggestion },
-    ...docs === void 0 ? {} : { docs },
-    ...requestId === void 0 ? {} : { requestId },
-    ...details === void 0 ? {} : { details },
-    ...parsed === void 0 ? {} : { body: parsed }
-  });
-}
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function tryParseJson(text) {
-  try {
-    return JSON.parse(text);
-  } catch {
-  }
-}
-
 // src/commands/analytics/event-counts.ts
+var ROW_ONLY_KEYS = {
+  cursor: "A grouped count is not paged; drop `cursor`.",
+  automationRunId: "`groupBy` and `bucket` count email events and do not combine with `automationRunId`."
+};
 var analyticsEventCountsCommand = defineCommand({
   path: ["analytics", "event-counts"],
   summary: "Count email events per field and/or period (clicks per link, events per day, unsubscribe reasons)",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "analytics.eventCounts",
   route: { method: "GET", path: "/v1/analytics/events" },
   commandClass: "read",
   flags: [
@@ -1018,21 +1299,27 @@ var analyticsEventCountsCommand = defineCommand({
         "Pass --group-by, --bucket, or both (`analytics events` lists the rows)."
       );
     }
-    const query = {};
-    for (const [key, value] of Object.entries(input)) {
-      if (key === "cursor" || key === "limit") {
-        continue;
+    for (const [key, reason] of Object.entries(ROW_ONLY_KEYS)) {
+      if (input[key] !== void 0) {
+        throw new CliUsageError(reason);
       }
-      query[key] = value === void 0 || value === null ? void 0 : Array.isArray(value) ? value.map(String).join(",") : String(value);
     }
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: "/v1/analytics/events",
-      query
-    });
+    const { limit: _pageSize, ...counted } = input;
+    const body = await ctx.client().analytics.eventCounts(
+      asSdkInput({
+        ...counted,
+        ...counted.groupBy === void 0 ? {} : { groupBy: toFieldList(counted.groupBy) }
+      })
+    );
     return { data: body, human: renderCounts(body) };
   }
 });
+function toFieldList(value) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  return value.split(",").map((field) => field.trim()).filter((field) => field !== "");
+}
 function renderCounts(body) {
   if (body.groups.length === 0) {
     return `No events counted (total ${body.count}).`;
@@ -1043,7 +1330,7 @@ function renderCounts(body) {
     count: group.count
   }));
   const table = renderTable(rows, [
-    { key: "group", header: "GROUP" },
+    ...rows.some((row) => row.group !== "") ? [{ key: "group", header: "GROUP" }] : [],
     ...rows.some((row) => "bucket" in row) ? [{ key: "bucket", header: "PERIOD" }] : [],
     { key: "count", header: "COUNT" }
   ]);
@@ -1402,7 +1689,171 @@ var analyticsTriggerInstancesListCommand = defineCommand({
     });
     return await listTriggerInstances(ctx, input, flags.all === true);
   }
-});
+});
+
+// src/lib/raw-request.ts
+var DEFAULT_ATTEMPT_TIMEOUT_MS = 3e4;
+async function rawFetch(ctx, request) {
+  const attempt = new AbortController();
+  const timer = setTimeout(() => {
+    attempt.abort(new CliTimeoutError(request.timeoutMs));
+  }, request.timeoutMs);
+  const combined = anySignal([ctx.signal, attempt.signal]);
+  const { signal } = combined;
+  if (signal.aborted) {
+    clearTimeout(timer);
+    combined.release();
+    throw signal.reason;
+  }
+  ctx.transport.record({
+    method: request.method,
+    path: apiPathOf(new URL(request.url)),
+    idempotencyKey: request.headers.get("idempotency-key") ?? void 0
+  });
+  try {
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers: request.headers,
+      signal,
+      ...request.body === void 0 ? {} : { body: request.body }
+    });
+    return { response, text: await readBodyText(response, signal) };
+  } catch (error) {
+    if (signal.aborted) {
+      throw signal.reason;
+    }
+    throw new CliConnectionError(error);
+  } finally {
+    clearTimeout(timer);
+    combined.release();
+  }
+}
+async function readBodyText(response, signal) {
+  if (response.body === null) {
+    return "";
+  }
+  const reader = response.body.getReader();
+  const onAbort = () => {
+    reader.cancel(signal.reason).catch(() => void 0);
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  const decoder = new TextDecoder();
+  let text = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      signal.throwIfAborted();
+      if (done) {
+        return text + decoder.decode();
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+async function rawRequest(ctx, request) {
+  const auth = resolveAuth({
+    globals: ctx.globals,
+    env: ctx.io.env,
+    ...request.allowAnonymous === true ? { allowAnonymous: true } : {}
+  });
+  const hasBody = request.body !== void 0;
+  const idempotencyKey = resolveRawIdempotencyKey(
+    request.method,
+    request.idempotencyKey
+  );
+  const headers = buildRawHeaders({
+    auth,
+    path: request.path,
+    hasJsonBody: hasBody,
+    idempotencyKey
+  });
+  const url = new URL(`${auth.apiUrl}${request.path}`);
+  for (const [key, value] of Object.entries(request.query ?? {})) {
+    if (value !== void 0) {
+      url.searchParams.set(key, value);
+    }
+  }
+  const { response, text } = await rawFetch(ctx, {
+    method: request.method,
+    url: url.toString(),
+    headers,
+    ...hasBody ? { body: JSON.stringify(request.body) } : {},
+    timeoutMs: ctx.budget.attemptMs ?? DEFAULT_ATTEMPT_TIMEOUT_MS
+  });
+  const parsed = tryParseJson(text);
+  if (!response.ok) {
+    throw responseToApiError(response, parsed);
+  }
+  if (parsed === void 0) {
+    throw new CliApiError({
+      status: response.status,
+      code: "UNEXPECTED_RESPONSE",
+      type: "internal_error",
+      message: "The API returned a non-JSON success response."
+    });
+  }
+  return parsed;
+}
+function resolveRawIdempotencyKey(method, provided) {
+  if (provided !== void 0 && provided !== "") {
+    return provided;
+  }
+  return method === "POST" ? crypto.randomUUID() : void 0;
+}
+function buildRawHeaders(input) {
+  const headers = new Headers({
+    authorization: `Bearer ${input.auth.apiKey}`,
+    "user-agent": `${CLI_NAME}/${CLI_VERSION}`,
+    accept: "application/json, text/plain;q=0.9"
+  });
+  if (input.hasJsonBody) {
+    headers.set("content-type", "application/json");
+  }
+  if (input.auth.brandId !== void 0 && !isOrgLevelPath(input.path)) {
+    headers.set("x-brand-id", input.auth.brandId);
+  }
+  if (input.idempotencyKey !== void 0 && input.idempotencyKey !== "") {
+    headers.set("idempotency-key", input.idempotencyKey);
+  }
+  return headers;
+}
+function responseToApiError(response, parsed) {
+  const requestId = response.headers.get("x-request-id") ?? void 0;
+  const record = isRecord2(parsed) ? parsed : void 0;
+  const standard = record !== void 0 && isRecord2(record.error) ? record.error : void 0;
+  const envelope = standard ?? record;
+  const readField = (key) => {
+    const value = envelope?.[key];
+    return typeof value === "string" ? value : void 0;
+  };
+  const param = readField("param");
+  const suggestion = readField("suggestion") ?? (envelope === void 0 ? void 0 : suggestionForStatus(response.status));
+  const docs = readField("docs");
+  const details = isRecord2(envelope?.details) ? envelope.details : void 0;
+  return new CliApiError({
+    status: response.status,
+    code: readField("code") ?? "HTTP_ERROR",
+    type: readField("type") ?? errorTypeForStatus(response.status),
+    message: readField("message") ?? `Request failed with status ${response.status}`,
+    ...param === void 0 ? {} : { param },
+    ...suggestion === void 0 ? {} : { suggestion },
+    ...docs === void 0 ? {} : { docs },
+    ...requestId === void 0 ? {} : { requestId },
+    ...details === void 0 ? {} : { details },
+    ...parsed === void 0 ? {} : { body: parsed }
+  });
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function tryParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+  }
+}
 
 // src/commands/api.ts
 var METHODS = ["GET", "POST", "PATCH", "DELETE"];
@@ -1432,7 +1883,7 @@ var apiCommand = defineCommand({
     },
     {
       flag: "--idempotency-key <key>",
-      summary: "Idempotency-Key header for safe POST retries"
+      summary: "Idempotency-Key header for safe POST retries (a POST gets one generated otherwise)"
     }
   ],
   examples: [
@@ -1464,7 +1915,7 @@ var apiCommand = defineCommand({
       auth,
       path,
       hasJsonBody: body !== void 0,
-      idempotencyKey: typeof flags.idempotencyKey === "string" ? flags.idempotencyKey : void 0
+      idempotencyKey: typeof flags.idempotencyKey === "string" && flags.idempotencyKey !== "" ? flags.idempotencyKey : method === "POST" ? crypto.randomUUID() : void 0
     });
     for (const header of readHeaderFlags(flags.header)) {
       const separator = header.indexOf(":");
@@ -1478,12 +1929,16 @@ var apiCommand = defineCommand({
         header.slice(separator + 1).trim()
       );
     }
-    const response = await fetch(`${auth.apiUrl}${path}`, {
+    const { response, text } = await rawFetch(ctx, {
       method,
+      url: `${auth.apiUrl}${path}`,
       headers,
-      ...body === void 0 ? {} : { body }
+      ...body === void 0 ? {} : { body },
+      // --timeout, else the SDK's own default for this route when it is a
+      // long-running one (`api POST /v1/emails` waits as long as `emails
+      // generate`), else the SDK's 30 s.
+      timeoutMs: ctx.budget.attemptMs ?? longRunningTimeoutMs({ method, path: barePath }) ?? DEFAULT_ATTEMPT_TIMEOUT_MS
     });
-    const text = await response.text();
     const parsed = tryParseJson(text);
     if (!response.ok) {
       throw responseToApiError(response, parsed);
@@ -1813,6 +2268,10 @@ var audiencesListCommand = defineCommand({
       flag: "--include <tokens>",
       summary: "0.6 flag: includes ride the detail read now (`audiences get --include count,build`)"
     },
+    {
+      flag: "--search <text>",
+      summary: "Only audiences whose name contains this text"
+    },
     LIMIT_FLAG,
     CURSOR_FLAG,
     ALL_FLAG,
@@ -1829,6 +2288,7 @@ var audiencesListCommand = defineCommand({
       throw includeRidesDetailRead("audiences get");
     }
     const input = mergeInput(base, {
+      search: flagString(flags.search),
       limit: flagInt(flags.limit, "--limit"),
       cursor: flagString(flags.cursor)
     });
@@ -1867,23 +2327,41 @@ function renderAudiences(rows) {
 // src/commands/audiences/update.ts
 var audiencesUpdateCommand = defineCommand({
   path: ["audiences", "update"],
-  summary: "Update an audience segment (name and/or filters)",
+  summary: "Update an audience segment: its name, its filters, or its members by email",
   sdkMethod: "audiences.update",
   route: { method: "PATCH", path: "/v1/audiences/{audienceId}" },
   commandClass: "write",
   args: [
     { name: "audienceId", summary: "Audience id to update", isRequired: true }
   ],
-  flags: [{ flag: "--name <name>", summary: "New audience name" }, INPUT_FLAG],
+  flags: [
+    { flag: "--name <name>", summary: "New audience name" },
+    {
+      flag: "--add-email <addresses...>",
+      summary: "Add these contacts by email, repeatable (refused when the filters cannot express it exactly)"
+    },
+    {
+      flag: "--remove-email <addresses...>",
+      summary: "Remove these contacts by email, repeatable (same rule)"
+    },
+    INPUT_FLAG
+  ],
   examples: [
     'brew-cli audiences update aud_3k9sQ --name "VIP customers"',
+    "brew-cli audiences update aud_3k9sQ --add-email ada@example.com --remove-email bo@example.com",
     `brew-cli audiences update aud_3k9sQ --input '{"filters":{"filters":[{"field":"plan","operator":"equals","value":"vip"}],"logicalOperator":"and"}}'`
   ],
   run: async ({ ctx, args, flags }) => {
     const base = await readJsonFlag(ctx, flags.input, "--input");
-    const input = mergeInput(base, { name: flagString(flags.name) });
+    const input = mergeInput(base, {
+      name: flagString(flags.name),
+      addEmails: toStringArray(flags.addEmail),
+      removeEmails: toStringArray(flags.removeEmail)
+    });
     if (Object.keys(input).length === 0) {
-      throw new CliUsageError("Nothing to update \u2014 pass --name or --input.");
+      throw new CliUsageError(
+        "Nothing to update \u2014 pass --name, --add-email, --remove-email or --input."
+      );
     }
     const result = await ctx.client().audiences.update(
       asSdkInput({
@@ -2236,7 +2714,16 @@ var automationsListCommand = defineCommand({
   sdkMethod: "automations.list",
   route: { method: "GET", path: "/v1/automations" },
   commandClass: "read",
-  flags: [LIMIT_FLAG, CURSOR_FLAG, ALL_FLAG, INPUT_FLAG],
+  flags: [
+    {
+      flag: "--search <text>",
+      summary: "Only automations whose name matches these words"
+    },
+    LIMIT_FLAG,
+    CURSOR_FLAG,
+    ALL_FLAG,
+    INPUT_FLAG
+  ],
   examples: [
     "brew-cli automations list",
     "brew-cli automations list --all --json"
@@ -2244,6 +2731,7 @@ var automationsListCommand = defineCommand({
   run: async ({ ctx, flags }) => {
     const base = await readJsonFlag(ctx, flags.input, "--input");
     const input = mergeInput(base, {
+      search: flagString(flags.search),
       limit: flagInt(flags.limit, "--limit"),
       cursor: flagString(flags.cursor)
     });
@@ -2632,17 +3120,14 @@ var FORMAT_FLAG = {
 var FORMATS = /* @__PURE__ */ new Set(["json", "ts", "zod", "jsonschema", "skill"]);
 var ENFORCEMENT_MODES = /* @__PURE__ */ new Set(["off", "prune", "strict"]);
 var VALIDATE_ENFORCEMENT_MODES = /* @__PURE__ */ new Set(["prune", "strict"]);
-function formatQuery(value) {
+function formatOption(value) {
   const format = flagString(value);
-  if (format === void 0) {
-    return "";
-  }
-  if (!FORMATS.has(format)) {
+  if (format !== void 0 && !FORMATS.has(format)) {
     throw new CliUsageError(
       `Unknown --format '${format}' (expected json | ts | zod | jsonschema | skill).`
     );
   }
-  return `?format=${format}`;
+  return format;
 }
 function contentHuman(body) {
   return typeof body.content === "string" ? { human: body.content } : {};
@@ -2650,8 +3135,7 @@ function contentHuman(body) {
 var automationsTriggersContractGetCommand = defineCommand({
   path: ["automations", "triggers", "contract", "get"],
   summary: "Read a trigger payload contract: stored when declared, derived otherwise; --format renders ts/zod/jsonschema/skill",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "automations.triggers.getContract",
   route: {
     method: "GET",
     path: "/v1/automations/triggers/{triggerEventId}/contract"
@@ -2671,18 +3155,20 @@ var automationsTriggersContractGetCommand = defineCommand({
     "brew-cli automations triggers contract get tri_signup --format skill --json | jq -r .content"
   ],
   run: async ({ ctx, args, flags }) => {
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/automations/triggers/${encodeURIComponent(args.triggerEventId ?? "")}/contract${formatQuery(flags.format)}`
-    });
+    const format = formatOption(flags.format);
+    const body = await ctx.client().automations.triggers.getContract(
+      asSdkInput({
+        triggerEventId: args.triggerEventId ?? "",
+        ...format === void 0 ? {} : { format }
+      })
+    );
     return { data: body, ...contentHuman(body) };
   }
 });
 var automationsTriggersContractPutCommand = defineCommand({
   path: ["automations", "triggers", "contract", "put"],
   summary: "Declare (or replace) the stored payload contract for a trigger \u2014 tree-validated before any write; omitting --enforcement leaves the stored setting unchanged",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "automations.triggers.putContract",
   route: {
     method: "PUT",
     path: "/v1/automations/triggers/{triggerEventId}/contract"
@@ -2734,19 +3220,19 @@ var automationsTriggersContractPutCommand = defineCommand({
         "Empty contract body \u2014 pass --input (fields and/or name) or --enforcement <mode>."
       );
     }
-    const body = await rawRequest(ctx, {
-      method: "PUT",
-      path: `/v1/automations/triggers/${encodeURIComponent(args.triggerEventId ?? "")}/contract`,
-      body: requestBody
-    });
+    const body = await ctx.client().automations.triggers.putContract(
+      asSdkInput({
+        ...requestBody,
+        triggerEventId: args.triggerEventId ?? ""
+      })
+    );
     return { data: body };
   }
 });
 var automationsTriggersContractValidateCommand = defineCommand({
   path: ["automations", "triggers", "contract", "validate"],
   summary: "Dry-run a payload against a trigger's contract (the fire path's validator) \u2014 never fires; invalid payloads still exit 0",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "automations.triggers.validatePayload",
   route: {
     method: "POST",
     path: "/v1/automations/triggers/{triggerEventId}/contract/validate"
@@ -2781,14 +3267,13 @@ var automationsTriggersContractValidateCommand = defineCommand({
         `Unknown --enforcement '${enforcement}' (expected prune | strict).`
       );
     }
-    const body = await rawRequest(ctx, {
-      method: "POST",
-      path: `/v1/automations/triggers/${encodeURIComponent(args.triggerEventId ?? "")}/contract/validate`,
-      body: {
+    const body = await ctx.client().automations.triggers.validatePayload(
+      asSdkInput({
+        triggerEventId: args.triggerEventId ?? "",
         payload,
         ...enforcement !== void 0 ? { enforcement } : {}
-      }
-    });
+      })
+    );
     return { data: body };
   }
 });
@@ -3164,8 +3649,7 @@ var RETIRED_FILTERS = {
 var brandGetImagesCommand = defineCommand({
   path: ["brand", "get-images"],
   summary: "Browse or semantically search the brand's assets (logos, brand images, images made with Brew)",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "brand.getImages",
   route: { method: "GET", path: "/v1/brand/images" },
   commandClass: "read",
   flags: [
@@ -3215,11 +3699,11 @@ var brandGetImagesCommand = defineCommand({
         throw new CliUsageError(message);
       }
     }
-    const page = (cursor) => rawRequest(ctx, {
-      method: "GET",
-      path: "/v1/brand/images",
-      query: toQuery(cursor === void 0 ? input : { ...input, cursor })
-    });
+    const page = (cursor) => ctx.client().brand.getImages(
+      asSdkInput(
+        cursor === void 0 ? input : { ...input, cursor }
+      )
+    );
     if (flags.all === true) {
       const rows = await collectAll(ctx, page);
       return {
@@ -3231,13 +3715,6 @@ var brandGetImagesCommand = defineCommand({
     return { data: result, human: renderAssets(result.data) };
   }
 });
-function toQuery(input) {
-  const query = {};
-  for (const [key, value] of Object.entries(input)) {
-    query[key] = value === void 0 || value === null ? void 0 : String(value);
-  }
-  return query;
-}
 function renderAssets(rows) {
   if (rows.length === 0) {
     return "No brand assets found.";
@@ -3538,6 +4015,90 @@ var contactsCountCommand = defineCommand({
   }
 });
 
+// src/commands/contacts/count-by.ts
+var contactsCountByCommand = defineCommand({
+  path: ["contacts", "count-by"],
+  summary: "Count contacts per field value, email domain, or signup period (largest group first)",
+  sdkMethod: "contacts.countBy",
+  route: { method: "POST", path: "/v1/contacts/search" },
+  commandClass: "read",
+  flags: [
+    {
+      flag: "--group-by <fields>",
+      summary: "One or two comma-separated fields: a contact field, a custom field, or emailDomain"
+    },
+    {
+      flag: "--bucket <period>",
+      summary: "Count per UTC day, week or month of createdAt"
+    },
+    { flag: "--search <text>", summary: "Free-text search" },
+    {
+      flag: "--filter <filters...>",
+      summary: "Structured filter field:operator[:value], repeatable"
+    },
+    { flag: "--audience <audienceId>", summary: "Scope to one audience" },
+    { flag: "--logic <logic>", summary: "Filter combinator: and | or" },
+    INPUT_FLAG
+  ],
+  examples: [
+    "brew-cli contacts count-by --group-by emailDomain",
+    "brew-cli contacts count-by --bucket month --filter subscribed:equals:true",
+    "brew-cli contacts count-by --group-by country,plan --json"
+  ],
+  run: async ({ ctx, flags }) => {
+    const base = await readJsonFlag(ctx, flags.input, "--input");
+    const input = mergeInput(base, {
+      groupBy: flagString(flags.groupBy),
+      bucket: flagString(flags.bucket),
+      search: flagString(flags.search),
+      filters: parseFilterFlags(flags.filter),
+      audienceId: flagString(flags.audience),
+      logic: flagString(flags.logic)
+    });
+    if (input.groupBy === void 0 && input.bucket === void 0) {
+      throw new CliUsageError(
+        "Pass --group-by, --bucket, or both (`contacts count` gives the total alone)."
+      );
+    }
+    const body = await ctx.client().contacts.countBy(
+      asSdkInput({
+        ...input,
+        ...input.groupBy === void 0 ? {} : { groupBy: toFieldList2(input.groupBy) }
+      })
+    );
+    return { data: body, human: renderCounts2(body) };
+  }
+});
+function toFieldList2(value) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  return value.split(",").map((field) => field.trim()).filter((field) => field !== "");
+}
+function renderCounts2(body) {
+  const groups = body.groups ?? [];
+  if (groups.length === 0) {
+    return `No contacts counted (total ${body.count}).`;
+  }
+  const rows = groups.map((group) => ({
+    group: Object.entries(group.key).map(([field, value]) => `${field}=${String(value)}`).join(" "),
+    ...group.bucket === void 0 || group.bucket === null ? {} : { bucket: group.bucket },
+    count: group.count
+  }));
+  const table = renderTable(rows, [
+    ...rows.some((row) => row.group !== "") ? [{ key: "group", header: "GROUP" }] : [],
+    ...rows.some((row) => "bucket" in row) ? [{ key: "bucket", header: "PERIOD" }] : [],
+    { key: "count", header: "COUNT" }
+  ]);
+  const otherCount = body.otherCount ?? 0;
+  const footer = [
+    `total ${body.count}`,
+    otherCount > 0 ? `${otherCount} in unlisted groups` : ""
+  ].filter(Boolean).join(" \xB7 ");
+  return `${table}
+${footer}`;
+}
+
 // src/commands/contacts/delete.ts
 var contactsDeleteCommand = defineCommand({
   path: ["contacts", "delete"],
@@ -4044,14 +4605,13 @@ var contentAddImageCommand = defineCommand({
     return { data: result };
   }
 });
-
-// src/commands/content/generate-image.ts
 var contentGenerateImageCommand = defineCommand({
   path: ["content", "generate-image"],
   summary: "Generate or edit an image from a prompt",
   sdkMethod: "content.generateImage",
   route: { method: "POST", path: "/v1/content/generate-image" },
   commandClass: "write",
+  defaultTimeoutMs: GENERATE_IMAGE_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   flags: [
     { flag: "--prompt <text>", summary: "What to generate" },
@@ -4092,14 +4652,13 @@ var contentGenerateImageCommand = defineCommand({
     return { data: result };
   }
 });
-
-// src/commands/content/gif.ts
 var contentGifCommand = defineCommand({
   path: ["content", "gif"],
   summary: "Create an animated GIF from a prompt, image, or video",
   sdkMethod: "content.gif",
   route: { method: "POST", path: "/v1/content/gif" },
   commandClass: "write",
+  defaultTimeoutMs: GIF_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   flags: [
     { flag: "--from <source>", summary: "prompt | image | video" },
@@ -4281,8 +4840,7 @@ var contentTransformCommand = defineCommand({
 var contractsInferCommand = defineCommand({
   path: ["contracts", "infer"],
   summary: "Draft a payload contract from a real example payload \u2014 nothing is saved; PUT the draft on a trigger",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "payloadContracts.infer",
   route: { method: "POST", path: "/v1/payload-contracts/infer" },
   commandClass: "read",
   flags: [INPUT_FLAG],
@@ -4305,14 +4863,12 @@ var contractsInferCommand = defineCommand({
         "--input with a non-empty example object is required (the JSON your system sends)."
       );
     }
-    const body = await rawRequest(ctx, {
-      method: "POST",
-      path: "/v1/payload-contracts/infer",
-      body: {
+    const body = await ctx.client().payloadContracts.infer(
+      asSdkInput({
         example,
         ...isEnvelope && input.subjectKind !== void 0 ? { subjectKind: input.subjectKind } : {}
-      }
-    });
+      })
+    );
     return { data: body };
   }
 });
@@ -4351,26 +4907,6 @@ var dataRunCommand = defineCommand({
 
 // src/skip-list.ts
 var SDK_SKIP_LIST = [
-  {
-    sdkPath: "automations.triggers.getContract",
-    reason: "covered by `automations triggers contract get` (raw route, bound pre-SDK-v9; SDK-method migration tracked separately)"
-  },
-  {
-    sdkPath: "automations.triggers.putContract",
-    reason: "covered by `automations triggers contract put` (raw route, bound pre-SDK-v9)"
-  },
-  {
-    sdkPath: "automations.triggers.validatePayload",
-    reason: "covered by `automations triggers contract validate` (raw route, bound pre-SDK-v9)"
-  },
-  {
-    sdkPath: "brand.getImages",
-    reason: "covered by `brand get-images` (raw route: SDK 10 cannot send `kind` or `sort`, brew-v2#1713; bind SDK 11.2)"
-  },
-  {
-    sdkPath: "payloadContracts.infer",
-    reason: "covered by `contracts infer` (raw route, bound pre-SDK-v9)"
-  },
   {
     sdkPath: "contacts.searchAll",
     reason: "auto-pager covered by `contacts search --all`"
@@ -4415,7 +4951,9 @@ function buildManifest() {
       "1": "API or runtime error",
       "2": "usage error",
       "3": "authentication error",
-      "4": "confirmation required (re-run with --yes)"
+      "4": "confirmation required (re-run with --yes)",
+      "130": "interrupted by SIGINT (Ctrl-C); the CLI then re-raises the signal",
+      "143": "terminated by SIGTERM; the CLI then re-raises the signal"
     },
     confirmationProtocol: {
       exitCode: 4,
@@ -4523,6 +5061,7 @@ var doctorCommand = defineCommand({
       isReachable = health.status === "ok";
       apiVersion = health.version ?? null;
     } catch (error) {
+      rethrowIfStopped(ctx);
       reachabilityError = error instanceof Error ? error.message : String(error);
     }
     let isAuthValid = null;
@@ -4533,6 +5072,7 @@ var doctorCommand = defineCommand({
         isAuthValid = true;
         plan = usage.plan?.key ?? null;
       } catch (error) {
+        rethrowIfStopped(ctx);
         if ((error instanceof BrewApiError || error instanceof CliApiError) && (error.status === 401 || error.status === 403)) {
           isAuthValid = false;
         }
@@ -4558,6 +5098,7 @@ var doctorCommand = defineCommand({
         extraLocally = [...localOps].filter((op) => !liveOps.has(op));
         isSurfaceChecked = true;
       } catch {
+        rethrowIfStopped(ctx);
       }
     }
     const isHealthy = isReachable && isAuthValid !== false && isSurfaceChecked && missingLocally.length === 0;
@@ -4595,6 +5136,9 @@ ${missingLocally.map((op) => `      ${op}`).join("\n")}` : "--  surface not chec
     };
   }
 });
+function rethrowIfStopped(ctx) {
+  ctx.signal.throwIfAborted();
+}
 
 // src/commands/domains/add.ts
 var domainsAddCommand = defineCommand({
@@ -4745,8 +5289,7 @@ function renderDomains(rows) {
 var domainsUnsubscribesAddCommand = defineCommand({
   path: ["domains", "unsubscribes", "add"],
   summary: "Add addresses to a marketing domain's unsubscribe list (that domain only)",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "domains.unsubscribes.add",
   route: { method: "POST", path: "/v1/domains/{domainId}/unsubscribes" },
   commandClass: "write",
   args: [
@@ -4767,12 +5310,10 @@ var domainsUnsubscribesAddCommand = defineCommand({
     if (emails === void 0) {
       throw new CliUsageError("Pass at least one --email.");
     }
-    const body = await rawRequest(ctx, {
-      method: "POST",
-      path: `/v1/domains/${encodeURIComponent(args.domainId ?? "")}/unsubscribes`,
-      body: { emails },
-      idempotencyKey: flagString(flags.idempotencyKey)
-    });
+    const body = await ctx.client().domains.unsubscribes.add(
+      { domainId: args.domainId ?? "", emails: [...emails] },
+      requestOptions(flags)
+    );
     return { data: body };
   }
 });
@@ -4781,8 +5322,7 @@ var domainsUnsubscribesAddCommand = defineCommand({
 var domainsUnsubscribesExportCommand = defineCommand({
   path: ["domains", "unsubscribes", "export"],
   summary: "A domain's unsubscribe list as CSV (truncated when capped)",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "domains.unsubscribes.export",
   route: {
     method: "GET",
     path: "/v1/domains/{domainId}/unsubscribes/export"
@@ -4802,11 +5342,13 @@ var domainsUnsubscribesExportCommand = defineCommand({
     "brew-cli domains unsubscribes export dom_123 --scope all --json"
   ],
   run: async ({ ctx, args, flags }) => {
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/domains/${encodeURIComponent(args.domainId ?? "")}/unsubscribes/export`,
-      query: { scope: flagString(flags.scope) }
-    });
+    const scope = flagString(flags.scope);
+    const body = await ctx.client().domains.unsubscribes.export(
+      asSdkInput({
+        domainId: args.domainId ?? "",
+        ...scope === void 0 ? {} : { scope }
+      })
+    );
     return { data: body, human: body.csv };
   }
 });
@@ -4815,8 +5357,7 @@ var domainsUnsubscribesExportCommand = defineCommand({
 var domainsUnsubscribesImportCommand = defineCommand({
   path: ["domains", "unsubscribes", "import"],
   summary: "Add every address in a CSV to a domain's unsubscribe list",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "domains.unsubscribes.import",
   route: {
     method: "POST",
     path: "/v1/domains/{domainId}/unsubscribes/import"
@@ -4844,12 +5385,14 @@ var domainsUnsubscribesImportCommand = defineCommand({
       );
     }
     const column = flagString(flags.column);
-    const body = await rawRequest(ctx, {
-      method: "POST",
-      path: `/v1/domains/${encodeURIComponent(args.domainId ?? "")}/unsubscribes/import`,
-      body: { csv, ...column === void 0 ? {} : { column } },
-      idempotencyKey: flagString(flags.idempotencyKey)
-    });
+    const body = await ctx.client().domains.unsubscribes.import(
+      {
+        domainId: args.domainId ?? "",
+        csv,
+        ...column === void 0 ? {} : { column }
+      },
+      requestOptions(flags)
+    );
     return { data: body };
   }
 });
@@ -4858,8 +5401,7 @@ var domainsUnsubscribesImportCommand = defineCommand({
 var domainsUnsubscribesListCommand = defineCommand({
   path: ["domains", "unsubscribes", "list"],
   summary: "One page of a marketing domain's unsubscribe list, newest first",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "domains.unsubscribes.list",
   route: { method: "GET", path: "/v1/domains/{domainId}/unsubscribes" },
   commandClass: "read",
   args: [
@@ -4880,16 +5422,18 @@ var domainsUnsubscribesListCommand = defineCommand({
   ],
   run: async ({ ctx, args, flags }) => {
     const limit = flagInt(flags.limit, "--limit");
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/domains/${encodeURIComponent(args.domainId ?? "")}/unsubscribes`,
-      query: {
-        q: flagString(flags.q),
-        scope: flagString(flags.scope),
-        limit: limit === void 0 ? void 0 : String(limit),
-        cursor: flagString(flags.cursor)
-      }
-    });
+    const q = flagString(flags.q);
+    const scope = flagString(flags.scope);
+    const cursor = flagString(flags.cursor);
+    const body = await ctx.client().domains.unsubscribes.list(
+      asSdkInput({
+        domainId: args.domainId ?? "",
+        ...q === void 0 ? {} : { q },
+        ...scope === void 0 ? {} : { scope },
+        ...limit === void 0 ? {} : { limit },
+        ...cursor === void 0 ? {} : { cursor }
+      })
+    );
     return { data: body, human: renderRows(body.data) };
   }
 });
@@ -4908,8 +5452,7 @@ function renderRows(rows) {
 var domainsUnsubscribesRemoveCommand = defineCommand({
   path: ["domains", "unsubscribes", "remove"],
   summary: "Take one address off a domain's unsubscribe list (never re-subscribes a brand-wide opt-out)",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "domains.unsubscribes.remove",
   route: {
     method: "DELETE",
     path: "/v1/domains/{domainId}/unsubscribes/{email}"
@@ -4922,9 +5465,9 @@ var domainsUnsubscribesRemoveCommand = defineCommand({
   flags: [],
   examples: ["brew-cli domains unsubscribes remove dom_123 ada@example.com"],
   run: async ({ ctx, args }) => ({
-    data: await rawRequest(ctx, {
-      method: "DELETE",
-      path: `/v1/domains/${encodeURIComponent(args.domainId ?? "")}/unsubscribes/${encodeURIComponent(args.email ?? "")}`
+    data: await ctx.client().domains.unsubscribes.remove({
+      domainId: args.domainId ?? "",
+      email: args.email ?? ""
     })
   })
 });
@@ -5002,6 +5545,7 @@ var emailsAuditCommand = defineCommand({
   sdkMethod: "emails.auditEmail",
   route: { method: "POST", path: "/v1/emails/audit" },
   commandClass: "write",
+  defaultTimeoutMs: AUDIT_EMAIL_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   flags: [
     {
@@ -5045,19 +5589,11 @@ var emailsAuditCommand = defineCommand({
         "--file is required (a path, or - for stdin), or emailHtml via --input."
       );
     }
-    const signal = AbortSignal.timeout(AUDIT_EMAIL_DEFAULT_TIMEOUT_MS);
-    try {
-      const result = await ctx.client().emails.auditEmail(asSdkInput(input), {
-        signal,
-        ...requestOptions(flags) ?? {}
-      });
-      return { data: result };
-    } catch (error) {
-      if (signal.aborted) {
-        throw signal.reason;
-      }
-      throw error;
-    }
+    const result = await ctx.client().emails.auditEmail(
+      asSdkInput(input),
+      requestOptions(flags)
+    );
+    return { data: result };
   }
 });
 
@@ -5195,8 +5731,6 @@ var emailsDeleteCommand = defineCommand({
     data: await ctx.client().emails.delete({ emailId: args.emailId ?? "" })
   })
 });
-
-// src/commands/emails/edit.ts
 var ENVELOPE_FIELDS = ["title", "subjectLine", "groupId"];
 function isText(value) {
   return typeof value === "string" && value !== "";
@@ -5207,6 +5741,7 @@ var emailsEditCommand = defineCommand({
   sdkMethod: "emails.edit",
   route: { method: "PATCH", path: "/v1/emails/{emailId}" },
   commandClass: "write",
+  defaultTimeoutMs: EDIT_EMAIL_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   args: [{ name: "emailId", summary: "Design id to edit", isRequired: true }],
   flags: [
@@ -5273,8 +5808,7 @@ var emailsEditCommand = defineCommand({
       isPromptEdit ? "Editing email\u2026 (typically 30-90s)" : envelope.length === 1 && envelope[0] === "subjectLine" ? "Setting the subject line\u2026" : "Updating the design (no AI run)\u2026"
     );
     const result = await ctx.client().emails.edit(
-      asSdkInput({ ...input, emailId: args.emailId ?? "" }),
-      { timeoutMs: 24e4 }
+      asSdkInput({ ...input, emailId: args.emailId ?? "" })
     );
     return { data: result };
   }
@@ -5335,14 +5869,13 @@ var emailsExportCommand = defineCommand({
     };
   }
 });
-
-// src/commands/emails/generate.ts
 var emailsGenerateCommand = defineCommand({
   path: ["emails", "generate"],
   summary: "Generate a new on-brand email design from a prompt",
   sdkMethod: "emails.generate",
   route: { method: "POST", path: "/v1/emails" },
   commandClass: "write",
+  defaultTimeoutMs: GENERATE_EMAIL_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   flags: [
     { flag: "--prompt <text>", summary: "What the email should be" },
@@ -5386,10 +5919,10 @@ var emailsGenerateCommand = defineCommand({
       );
     }
     progress(ctx, "Generating email\u2026 (typically 30-90s)");
-    const result = await ctx.client().emails.generate(asSdkInput(input), {
-      timeoutMs: 24e4,
-      ...requestOptions(flags) ?? {}
-    });
+    const result = await ctx.client().emails.generate(
+      asSdkInput(input),
+      requestOptions(flags)
+    );
     return { data: result };
   }
 });
@@ -5438,16 +5971,11 @@ var emailsGetCommand = defineCommand({
         "Pass --email-version-id or --run-id, not both: each selects the version to read."
       );
     }
-    if (emailVersionId === void 0 && runId === void 0) {
-      return {
-        data: await ctx.client().emails.get(emailId, include === void 0 ? void 0 : { include })
-      };
-    }
     return {
-      data: await rawRequest(ctx, {
-        method: "GET",
-        path: `/v1/emails/${encodeURIComponent(emailId)}`,
-        query: { include, emailVersionId, runId }
+      data: await ctx.client().emails.get(emailId, {
+        ...include === void 0 ? {} : { include },
+        ...emailVersionId === void 0 ? {} : { emailVersionId },
+        ...runId === void 0 ? {} : { runId }
       })
     };
   }
@@ -5457,8 +5985,7 @@ var emailsGetCommand = defineCommand({
 var emailsGetAuditCommand = defineCommand({
   path: ["emails", "get-audit"],
   summary: "Read a saved email audit: one page of its findings (free; never reruns the audit)",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "emails.getAudit",
   route: { method: "GET", path: "/v1/emails/audits/{auditId}" },
   commandClass: "read",
   args: [
@@ -5482,13 +6009,10 @@ var emailsGetAuditCommand = defineCommand({
   // says whether one exists.
   run: async ({ ctx, args, flags }) => {
     const limit = flagInt(flags.limit, "--limit");
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/emails/audits/${encodeURIComponent(args.auditId ?? "")}`,
-      query: {
-        cursor: flagString(flags.cursor),
-        limit: limit === void 0 ? void 0 : String(limit)
-      }
+    const cursor = flagString(flags.cursor);
+    const body = await ctx.client().emails.getAudit(args.auditId ?? "", {
+      ...cursor === void 0 ? {} : { cursor },
+      ...limit === void 0 ? {} : { limit }
     });
     return { data: body };
   }
@@ -5498,8 +6022,7 @@ var emailsGetAuditCommand = defineCommand({
 var emailsGetClientPreviewCommand = defineCommand({
   path: ["emails", "get-client-preview"],
   summary: "Poll a client-preview rendering job: per-client screenshot links once it settles (free; never re-renders)",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "emails.getClientPreview",
   route: { method: "GET", path: "/v1/emails/client-previews/{previewId}" },
   commandClass: "read",
   args: [
@@ -5518,10 +6041,7 @@ var emailsGetClientPreviewCommand = defineCommand({
   // `failed`; each client then carries its `imageUrl`, or a `reason` and
   // whether it is `retryable`.
   run: async ({ ctx, args }) => {
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/emails/client-previews/${encodeURIComponent(args.previewId ?? "")}`
-    });
+    const body = await ctx.client().emails.getClientPreview(args.previewId ?? "");
     return { data: body };
   }
 });
@@ -5735,14 +6255,13 @@ var emailsGroupsUpdateCommand = defineCommand({
     };
   }
 });
-
-// src/commands/emails/import.ts
 var emailsImportCommand = defineCommand({
   path: ["emails", "import"],
   summary: "Import existing HTML, MJML, or JSX as a new editable design",
   sdkMethod: "emails.import",
   route: { method: "POST", path: "/v1/emails/import" },
   commandClass: "write",
+  defaultTimeoutMs: IMPORT_EMAIL_DEFAULT_TIMEOUT_MS,
   flags: [
     {
       flag: "--file <path>",
@@ -5788,14 +6307,13 @@ var emailsImportCommand = defineCommand({
     return { data: result };
   }
 });
-
-// src/commands/emails/import-figma.ts
 var emailsImportFigmaCommand = defineCommand({
   path: ["emails", "import-figma"],
   summary: "Convert one Figma frame into an editable design (deterministic, free)",
   sdkMethod: "emails.importFigma",
   route: { method: "POST", path: "/v1/emails/figma" },
   commandClass: "write",
+  defaultTimeoutMs: IMPORT_FIGMA_DEFAULT_TIMEOUT_MS,
   flags: [
     {
       flag: "--url <figmaUrl>",
@@ -5896,6 +6414,10 @@ var emailsListCommand = defineCommand({
   route: { method: "GET", path: "/v1/emails" },
   commandClass: "read",
   flags: [
+    {
+      flag: "--search <text>",
+      summary: "Only designs whose title contains this text, or whose title, subject, preview or text matches its words"
+    },
     {
       flag: "--status <status>",
       summary: "Filter by status: generating | ready | failed"
@@ -5955,6 +6477,7 @@ var emailsListCommand = defineCommand({
     );
     const base = await readJsonFlag(ctx, flags.input, "--input");
     const input = mergeInput(base, {
+      search: flagString(flags.search),
       status: flagString(flags.status),
       groupId: flagString(flags.groupId),
       sortBy: flagString(flags.sortBy) ?? flagString(flags.sort) ?? legacy.sortBy,
@@ -6029,14 +6552,13 @@ function renderEmails(rows) {
     { key: "updatedAt", header: "UPDATED" }
   ]);
 }
-
-// src/commands/emails/preview-clients.ts
 var emailsPreviewClientsCommand = defineCommand({
   path: ["emails", "preview-clients"],
   summary: "Start a rendering job across real email clients (10 credits); poll it with `emails get-client-preview`",
   sdkMethod: "emails.previewClients",
   route: { method: "POST", path: "/v1/emails/{emailId}/client-previews" },
   commandClass: "write",
+  defaultTimeoutMs: PREVIEW_EMAIL_CLIENTS_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   args: [
     { name: "emailId", summary: "Design id to preview", isRequired: true }
@@ -6616,7 +7138,7 @@ var loginCommand = defineCommand({
       globals: { ...ctx.globals, apiKey: candidate },
       env: ctx.io.env
     });
-    await buildSdkClient(auth).usage.get();
+    await buildSdkClient(auth, sdkTransportFor(ctx)).usage.get();
     const path = updateConfig(ctx.io.env, { apiKey: candidate });
     progress(ctx, `Logged in. Key stored in ${path} (0600).`);
     return {
@@ -6743,8 +7265,7 @@ var sendsResumeCommand = defineCommand({
 var templatesGetCommand = defineCommand({
   path: ["templates", "get"],
   summary: "Fetch one public template: its links and the referenceEmailId to remix; --include html adds its HTML",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "templates.get",
   route: { method: "GET", path: "/v1/templates/{templateId}" },
   commandClass: "read",
   args: [
@@ -6765,11 +7286,11 @@ var templatesGetCommand = defineCommand({
     "brew-cli templates get seed-vercel-newsletter --include html --json"
   ],
   run: async ({ ctx, args, flags }) => {
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/templates/${encodeURIComponent(args.templateId ?? "")}`,
-      query: { include: flagString(flags.include) }
-    });
+    const include = flagString(flags.include);
+    const body = await ctx.client().templates.get(
+      args.templateId ?? "",
+      include === void 0 ? void 0 : { include: asSdkInput(include) }
+    );
     return { data: body };
   }
 });
@@ -7055,6 +7576,7 @@ var whoamiCommand = defineCommand({
       if (error instanceof BrewApiError && (error.status === 401 || error.status === 403)) {
         throw error;
       }
+      ctx.signal.throwIfAborted();
       progress(
         ctx,
         "Warning: could not reach /v1/usage \u2014 showing local credential state only."
@@ -7085,6 +7607,7 @@ var ALL_COMMANDS = [
   contactsSearchCommand,
   contactsGetCommand,
   contactsCountCommand,
+  contactsCountByCommand,
   contactsUpsertCommand,
   contactsUpsertManyCommand,
   contactsUpdateCommand,
@@ -7251,6 +7774,7 @@ Environment:
 Exit codes:
   0 success \xB7 1 API/runtime error \xB7 2 usage error \xB7 3 auth error
   4 confirmation required (re-run with --yes)
+  130 interrupted (SIGINT) \xB7 143 terminated (SIGTERM)
 
 Agents: run \`${CLI_NAME} docs --agent\` for the machine-readable manifest.
 `;
@@ -7268,8 +7792,8 @@ async function run(argv, io, commands = ALL_COMMANDS) {
     (text) => {
       commanderStderr.push(text);
     },
-    (code) => {
-      commandExitCode = code;
+    (code2) => {
+      commandExitCode = code2;
     }
   );
   const flushCommanderStderr = () => {
@@ -7289,9 +7813,51 @@ async function run(argv, io, commands = ALL_COMMANDS) {
     }
     flushCommanderStderr();
     const ctx = activeContext ?? makeFallbackContext(io, argv);
-    printError(ctx, error);
-    return toExitCode(error);
+    const reported = reportedError(ctx, error);
+    printError(ctx, reported, errorContextFor(ctx, commands));
+    return toExitCode(reported);
+  }
+}
+function reportedError(ctx, error) {
+  if (!ctx.signal.aborted) {
+    return error;
+  }
+  if (error instanceof BrewApiError || error instanceof CliApiError) {
+    return error;
   }
+  return ctx.signal.reason;
+}
+function errorContextFor(ctx, commands) {
+  const request = ctx.transport.lastRequest();
+  const drain = ctx.transport.drain();
+  const bound = request === void 0 ? void 0 : commandFor(request, commands);
+  const isRead = bound === void 0 ? ctx.traits?.isRead : bound.commandClass === "read";
+  return {
+    ...request === void 0 ? {} : { request },
+    ...drain === void 0 ? {} : { drain },
+    ...isRead === void 0 ? {} : { isRead },
+    replays: bound === void 0 ? ctx.traits?.replays === true : (bound.flags ?? []).includes(IDEMPOTENCY_FLAG),
+    readsStdin: readsStdin(ctx.rawArgv),
+    retryCommand: (key) => buildRetryCommand(ctx.rawArgv, key)
+  };
+}
+function commandFor(request, commands) {
+  const apiPath = request.path.split("?")[0] ?? "";
+  return commands.find(
+    (spec) => spec.route !== void 0 && spec.route.method === request.method && matchesTemplate(spec.route.path, apiPath)
+  );
+}
+function readsStdin(rawArgv) {
+  return rawArgv.some(
+    (token, index) => token === "-" && ["--input", "--file", "--data"].includes(rawArgv[index - 1] ?? "")
+  );
+}
+function traitsOf(spec) {
+  return {
+    isRead: spec.commandClass === "read",
+    replays: (spec.flags ?? []).includes(IDEMPOTENCY_FLAG),
+    defaultTimeoutMs: spec.defaultTimeoutMs
+  };
 }
 function handleCommanderError(error, ctx, flush) {
   const isHelpCode = error.code === "commander.helpDisplayed" || error.code === "commander.help";
@@ -7380,16 +7946,21 @@ function registerCommand(program, spec, io, rawArgv, onContext, onExitCode) {
       },
       {}
     );
-    const ctx = makeContext({ io, flags, rawArgv });
+    const ctx = makeContext({ io, flags, rawArgv, traits: traitsOf(spec) });
     onContext?.(ctx);
     const invocation = { ctx, args: positional, flags };
     await enforceConfirmation(spec, invocation);
-    const outcome = await spec.run(invocation);
-    if (outcome !== void 0) {
-      printData(ctx, outcome.data, outcome.human);
-      if (outcome.exitCode !== void 0 && outcome.exitCode !== 0) {
-        onExitCode?.(outcome.exitCode);
+    ctx.startDeadline();
+    try {
+      const outcome = await spec.run(invocation);
+      if (outcome !== void 0) {
+        printData(ctx, outcome.data, outcome.human);
+        if (outcome.exitCode !== void 0 && outcome.exitCode !== 0) {
+          onExitCode?.(outcome.exitCode);
+        }
       }
+    } finally {
+      ctx.stopDeadline();
     }
   });
 }
@@ -7428,20 +7999,77 @@ function buildCommandHelpFooter(spec) {
   return lines.join("\n");
 }
 
+// src/lib/interrupt.ts
+function createInterrupter(input) {
+  const controller = new AbortController();
+  const graceMs = input.graceMs ?? 3e3;
+  let first;
+  let grace;
+  const forceExit = (signal, why) => {
+    input.stderr.write(`
+brew-cli: ${why}; exiting without waiting.
+`);
+    input.exit(exitCodeForSignal(signal));
+  };
+  const trigger = (signal) => {
+    if (first !== void 0) {
+      forceExit(signal, `${signal} received twice`);
+      return;
+    }
+    first = signal;
+    controller.abort(new CliInterruptError(signal));
+    grace = setTimeout(() => {
+      forceExit(signal, `still stopping ${graceMs / 1e3}s after ${signal}`);
+    }, graceMs);
+    grace.unref?.();
+  };
+  input.source.on("SIGINT", () => {
+    trigger("SIGINT");
+  });
+  input.source.on("SIGTERM", () => {
+    trigger("SIGTERM");
+  });
+  return {
+    signal: controller.signal,
+    trigger,
+    received: () => first,
+    settle: () => {
+      if (grace !== void 0) {
+        clearTimeout(grace);
+      }
+    }
+  };
+}
+
 // src/bin.ts
-function realIo() {
+function realIo(interrupter2) {
+  const { signal } = interrupter2;
   return {
     stdout: process.stdout,
     stderr: process.stderr,
     isTtyOut: process.stdout.isTTY === true,
     isTtyIn: process.stdin.isTTY === true,
     env: process.env,
+    signal,
     readStdin: async () => {
+      const stop = () => {
+        process.stdin.destroy();
+      };
+      signal.addEventListener("abort", stop, { once: true });
       process.stdin.setEncoding("utf8");
       let data = "";
-      for await (const chunk of process.stdin) {
-        data += chunk;
+      try {
+        for await (const chunk of process.stdin) {
+          data += chunk;
+        }
+      } catch (error) {
+        if (!signal.aborted) {
+          throw error;
+        }
+      } finally {
+        signal.removeEventListener("abort", stop);
       }
+      signal.throwIfAborted();
       return data;
     },
     readLine: async (prompt) => {
@@ -7449,14 +8077,34 @@ function realIo() {
         input: process.stdin,
         output: process.stderr
       });
+      rl.on("SIGINT", () => {
+        interrupter2.trigger("SIGINT");
+      });
       try {
-        return await rl.question(prompt);
+        return await rl.question(prompt, { signal });
       } finally {
         rl.close();
       }
     }
   };
 }
-process.exitCode = await run(process.argv.slice(2), realIo());
+var interrupter = createInterrupter({
+  source: process,
+  stderr: process.stderr,
+  exit: (code2) => process.exit(code2)
+});
+var code = await run(process.argv.slice(2), realIo(interrupter));
+interrupter.settle();
+process.exitCode = code;
+var received = interrupter.received();
+if (received !== void 0 && code === exitCodeForSignal(received) && process.platform !== "win32") {
+  await new Promise((resolve) => {
+    process.stderr.write("", () => {
+      resolve();
+    });
+  });
+  process.removeAllListeners(received);
+  process.kill(process.pid, received);
+}
 //# sourceMappingURL=bin.js.map
 //# sourceMappingURL=bin.js.map