feat: add --dry-run flag to mutating commands

docs/src/content/docs/commands/api.md

@@ -85,17 +85,20 @@ sentry api /organizations/ \
   --header "X-Custom-Header:value"
 ```
 
-### Show Response Headers
+### Verbose Mode
 
 ```bash
-sentry api /organizations/ --include
+sentry api /organizations/ --verbose
 ```
 
-```
-HTTP/2 200
-content-type: application/json
-x-sentry-rate-limit-remaining: 95
+Request and response metadata is logged to stderr:
 
+```
+> GET /api/0/organizations/
+>
+< HTTP 200
+< content-type: application/json
+<
 [{"slug": "my-org", ...}]
 ```
 

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -163,6 +163,7 @@ Create a new project
 
 **Flags:**
 - `-t, --team <value> - Team to create the project under`
+- `-n, --dry-run - Validate inputs and show what would be created without creating it`
 - `--json - Output as JSON`
 - `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
@@ -395,9 +396,11 @@ Make an authenticated API request
 - `-f, --raw-field <value>... - Add a string parameter without JSON parsing`
 - `-H, --header <value>... - Add a HTTP request header in key:value format`
 - `--input <value> - The file to use as body for the HTTP request (use "-" to read from standard input)`
-- `-i, --include - Include HTTP response status line and headers in the output`
 - `--silent - Do not print the response body`
 - `--verbose - Include full HTTP request and response in the output`
+- `-n, --dry-run - Show the resolved request without sending it`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -436,7 +439,7 @@ sentry api /projects/my-org/my-project/ \
 sentry api /organizations/ \
   --header "X-Custom-Header:value"
 
-sentry api /organizations/ --include
+sentry api /organizations/ --verbose
 
 # Get all issues (automatically follows pagination)
 sentry api /projects/my-org/my-project/issues/ --paginate

src/commands/api.ts

@@ -6,10 +6,12 @@
  */
 
 import type { SentryContext } from "../context.js";
-import { rawApiRequest } from "../lib/api-client.js";
+import { buildSearchParams, rawApiRequest } from "../lib/api-client.js";
 import { buildCommand } from "../lib/command.js";
-import { ValidationError } from "../lib/errors.js";
+import { OutputError, ValidationError } from "../lib/errors.js";
 import { validateEndpoint } from "../lib/input-validation.js";
+import { logger } from "../lib/logger.js";
+import { getDefaultSdkConfig } from "../lib/sentry-client.js";
 import type { Writer } from "../types/index.js";
 
 type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
@@ -21,9 +23,13 @@ type ApiFlags = {
   readonly "raw-field"?: string[];
   readonly header?: string[];
   readonly input?: string;
-  readonly include: boolean;
   readonly silent: boolean;
   readonly verbose: boolean;
+  readonly "dry-run": boolean;
+  /** Injected by buildCommand via output config */
+  readonly json: boolean;
+  /** Injected by buildCommand via output config */
+  readonly fields?: string[];
 };
 
 // Request Parsing
@@ -842,105 +848,65 @@ export function buildBodyFromFields(
 // Response Output
 
 /**
- * Write response headers to stdout (standard format)
+ * Format a raw response body value for human-readable output.
+ * Objects are pretty-printed as JSON, strings pass through, null/undefined → empty.
  * @internal Exported for testing
  */
-export function writeResponseHeaders(
-  stdout: Writer,
-  status: number,
-  headers: Headers
-): void {
-  stdout.write(`HTTP ${status}\n`);
-  headers.forEach((value, key) => {
-    stdout.write(`${key}: ${value}\n`);
-  });
-  stdout.write("\n");
-}
-
-/**
- * Write response body to stdout
- * @internal Exported for testing
- */
-export function writeResponseBody(stdout: Writer, body: unknown): void {
-  if (body === null || body === undefined) {
-    return;
+export function formatApiResponse(data: unknown): string {
+  if (data === null || data === undefined) {
+    return "";
   }
-
-  if (typeof body === "object") {
-    stdout.write(`${JSON.stringify(body, null, 2)}\n`);
-  } else {
-    stdout.write(`${String(body)}\n`);
+  if (typeof data === "object") {
+    return JSON.stringify(data, null, 2);
   }
+  return String(data);
 }
 
 /**
- * Write verbose request output (curl-style format)
+ * Resolve the full URL that rawApiRequest would use for a request.
+ *
+ * Mirrors the URL construction in rawApiRequest:
+ * `${baseUrl}/api/0/${endpoint}?${queryString}`
  * @internal Exported for testing
  */
-export function writeVerboseRequest(
-  stdout: Writer,
-  method: string,
+export function resolveRequestUrl(
   endpoint: string,
-  headers: Record<string, string> | undefined
-): void {
-  stdout.write(`> ${method} /api/0/${endpoint}\n`);
-  if (headers) {
-    for (const [key, value] of Object.entries(headers)) {
-      stdout.write(`> ${key}: ${value}\n`);
-    }
-  }
-  stdout.write(">\n");
+  params?: Record<string, string | string[]>
+): string {
+  // Use getDefaultSdkConfig().baseUrl — same as rawApiRequest — to ensure
+  // trailing slashes are stripped and the URL matches what would be sent.
+  const { baseUrl } = getDefaultSdkConfig();
+  const normalizedEndpoint = endpoint.startsWith("/")
+    ? endpoint.slice(1)
+    : endpoint;
+  const searchParams = buildSearchParams(params);
+  const queryString = searchParams ? `?${searchParams.toString()}` : "";
+  return `${baseUrl}/api/0/${normalizedEndpoint}${queryString}`;
 }
 
 /**
- * Write verbose response output (curl-style format)
- * @internal Exported for testing
- */
-export function writeVerboseResponse(
-  stdout: Writer,
-  status: number,
-  headers: Headers
-): void {
-  stdout.write(`< HTTP ${status}\n`);
-  headers.forEach((value, key) => {
-    stdout.write(`< ${key}: ${value}\n`);
-  });
-  stdout.write("<\n");
-}
-
-/**
- * Handle response output based on flags
+ * Resolve effective request headers, mirroring rawApiRequest logic.
+ *
+ * Auto-adds Content-Type: application/json for non-string object bodies
+ * when no Content-Type was explicitly provided.
+ *
  * @internal Exported for testing
  */
-export function handleResponse(
-  stdout: Writer,
-  response: { status: number; headers: Headers; body: unknown },
-  flags: { silent: boolean; verbose: boolean; include: boolean }
-): void {
-  const isError = response.status >= 400;
-
-  // Silent mode - only set exit code
-  if (flags.silent) {
-    if (isError) {
-      process.exit(1);
-    }
-    return;
-  }
-
-  // Output headers (verbose or include mode)
-  if (flags.verbose) {
-    writeVerboseResponse(stdout, response.status, response.headers);
-  } else if (flags.include) {
-    writeResponseHeaders(stdout, response.status, response.headers);
-  }
-
-  // Output body
-  writeResponseBody(stdout, response.body);
-
-  // Exit with error code for error responses
-  if (isError) {
-    process.exit(1);
+export function resolveEffectiveHeaders(
+  customHeaders: Record<string, string> | undefined,
+  body: unknown
+): Record<string, string> {
+  // Mirror rawApiRequest exactly: auto-add Content-Type for any non-string,
+  // non-undefined body when no Content-Type was explicitly provided.
+  const isStringBody = typeof body === "string";
+  const headers = { ...(customHeaders ?? {}) };
+  const hasContentType = Object.keys(headers).some(
+    (k) => k.toLowerCase() === "content-type"
+  );
+  if (!(isStringBody || hasContentType) && body !== undefined) {
+    headers["Content-Type"] = "application/json";
   }
+  return headers;
 }
 
 /**
@@ -1065,7 +1031,34 @@ export async function resolveBody(
 
 // Command Definition
 
+const log = logger.withTag("api");
+
+/** Log outgoing request details in `> ` curl-verbose style. */
+function logRequest(
+  method: string,
+  endpoint: string,
+  headers: Record<string, string> | undefined
+): void {
+  log.debug(`> ${method} /api/0/${endpoint}`);
+  if (headers) {
+    for (const [key, value] of Object.entries(headers)) {
+      log.debug(`> ${key}: ${value}`);
+    }
+  }
+  log.debug(">");
+}
+
+/** Log incoming response details in `< ` curl-verbose style. */
+function logResponse(response: { status: number; headers: Headers }): void {
+  log.debug(`< HTTP ${response.status}`);
+  response.headers.forEach((value, key) => {
+    log.debug(`< ${key}: ${value}`);
+  });
+  log.debug("<");
+}
+
 export const apiCommand = buildCommand({
+  output: { json: true, human: formatApiResponse },
   docs: {
     brief: "Make an authenticated API request",
     fullDescription:
@@ -1143,11 +1136,6 @@ export const apiCommand = buildCommand({
         optional: true,
         placeholder: "file",
       },
-      include: {
-        kind: "boolean",
-        brief: "Include HTTP response status line and headers in the output",
-        default: false,
-      },
       silent: {
         kind: "boolean",
         brief: "Do not print the response body",
@@ -1158,37 +1146,48 @@ export const apiCommand = buildCommand({
         brief: "Include full HTTP request and response in the output",
         default: false,
       },
+      "dry-run": {
+        kind: "boolean",
+        brief: "Show the resolved request without sending it",
+        default: false,
+      },
     },
     aliases: {
       X: "method",
       d: "data",
       F: "field",
       f: "raw-field",
       H: "header",
-      i: "include",
+      n: "dry-run",
     },
   },
-  async func(
-    this: SentryContext,
-    flags: ApiFlags,
-    endpoint: string
-  ): Promise<void> {
-    const { stdout, stderr, stdin } = this;
-
-    // Normalize endpoint to ensure trailing slash (Sentry API requirement)
-    const normalizedEndpoint = normalizeEndpoint(endpoint);
+  async func(this: SentryContext, flags: ApiFlags, endpoint: string) {
+    const { stderr, stdin } = this;
 
-    // Resolve body and query params from flags (--data, --input, or fields)
+    const normalizedEndpoint = normalizeEndpoint(endpoint);
     const { body, params } = await resolveBody(flags, stdin, stderr);
 
     const headers =
       flags.header && flags.header.length > 0
         ? parseHeaders(flags.header)
         : undefined;
 
-    // Verbose mode: show request details (unless silent)
-    if (flags.verbose && !flags.silent) {
-      writeVerboseRequest(stdout, flags.method, normalizedEndpoint, headers);
+    // Dry-run mode: preview the request that would be sent
+    if (flags["dry-run"]) {
+      return {
+        data: {
+          method: flags.method,
+          url: resolveRequestUrl(normalizedEndpoint, params),
+          headers: resolveEffectiveHeaders(headers, body),
+          body: body ?? null,
+        },
+      };
+    }
+
+    const verbose = flags.verbose && !flags.silent;
+
+    if (verbose) {
+      logRequest(flags.method, normalizedEndpoint, headers);
     }
 
     const response = await rawApiRequest(normalizedEndpoint, {
@@ -1198,6 +1197,25 @@ export const apiCommand = buildCommand({
       headers,
     });
 
-    handleResponse(stdout, response, flags);
+    const isError = response.status >= 400;
+
+    if (verbose) {
+      logResponse(response);
+    }
+
+    // Silent mode — no output, just exit code
+    if (flags.silent) {
+      if (isError) {
+        throw new OutputError(null);
+      }
+      return;
+    }
+
+    // Always return raw body — --fields filters it directly
+    if (isError) {
+      throw new OutputError(response.body);
+    }
+
+    return { data: response.body };
   },
 });