feat(api): add --data/-d flag and auto-detect JSON body in fields (#320)

## Summary

Fixes [CLI-AF](https://sentry.sentry.io/issues/CLI-AF) — users passing
raw JSON as `--raw-field` now get auto-correction instead of a cryptic
error.

## Problem

A user ran:
```bash
sentry api /api/0/issues/7303827789/ -X PUT -f '{"status":"ignored","statusDetails":{"ignoreCount":1}}'
```
and got: `Error: Invalid field format: {...}. Expected key=value`

Worse, on current main, `normalizeFields` would silently *mangle* the
JSON by converting the first `:` to `=`, producing
`{"status"="ignored",...}` — silent data corruption sent to the API.

## Changes

### 1. `--data`/`-d` flag (like curl)

New explicit inline JSON body flag, following curl convention:

```bash
sentry api issues/123/ -X PUT -d '{"status":"resolved"}'
```

- Tries `JSON.parse()`, falls back to raw string (like `--input`)
- Mutually exclusive with `--input` (clear `ValidationError` if both
used)

### 2. JSON auto-detection in field values

When someone passes `-f '{"status":"ignored"}'`, we detect it's JSON (no
`=`, starts with `{`/`[`, valid `JSON.parse`), use it as the request
body, and hint:

```
hint: '{"status":"ignored"}' was used as the request body. Use --data/-d to pass inline JSON next time.
```

If there are also normal `key=value` fields, they're merged into the
JSON body. Multiple bare JSON fields throw a `ValidationError`.

### 3. `normalizeFields` JSON guard

Skip colon→equals auto-correction for strings starting with `{` or `[`.
This fixes the **silent data corruption bug** where JSON was mangled
into garbage.

## Tests

30 new tests across 4 describe blocks:
- `normalizeFields` — JSON passthrough (objects, arrays, mixed with
other fields)
- `parseDataBody` — valid JSON, arrays, nested, invalid, partial
- `extractJsonBody` — extraction + hint, remaining fields, invalid JSON,
multiple JSON error, key=value with JSON value, preview truncation
- `buildFromFields` — CLI-AF scenario, merge JSON + fields, GET params
routing, no-JSON passthrough

All 2312 unit tests pass. Typecheck and lint clean.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: BYK

AGENTS.md

@@ -354,6 +354,7 @@ Make an authenticated API request
 
 **Flags:**
 - `-X, --method <value> - The HTTP method for the request - (default: "GET")`
+- `-d, --data <value> - Inline JSON body for the request (like curl -d)`
 - `-F, --field <value>... - Add a typed parameter (key=value, key[sub]=value, key[]=value)`
 - `-f, --raw-field <value>... - Add a string parameter without JSON parsing`
 - `-H, --header <value>... - Add a HTTP request header in key:value format`

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

@@ -15,6 +15,7 @@ type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
 
 type ApiFlags = {
   readonly method: HttpMethod;
+  readonly data?: string;
   readonly field?: string[];
   readonly "raw-field"?: string[];
   readonly header?: string[];
@@ -333,6 +334,13 @@ export function normalizeFields(
       return field;
     }
 
+    // JSON-shaped strings (starting with { or [) must not be "corrected" —
+    // the colon inside is JSON syntax, not a key:value separator.  Let the
+    // downstream pipeline handle it (extractJsonBody or processField error).
+    if (field.startsWith("{") || field.startsWith("[")) {
+      return field;
+    }
+
     const colonIndex = field.indexOf(":");
     // ':' must exist and not be the very first character (that would make an
     // empty key, which the parser rejects regardless)
@@ -600,6 +608,109 @@ export function parseHeaders(headers: string[]): Record<string, string> {
 
 // Request Body Building
 
+/**
+ * Parse an inline string as a request body.  Tries JSON first; falls back to
+ * the raw string so non-JSON payloads still work.
+ *
+ * @param data - Raw string from --data flag
+ * @returns Parsed JSON object/array, or the original string
+ * @internal Exported for testing
+ */
+export function parseDataBody(
+  data: string
+): Record<string, unknown> | unknown[] | string {
+  try {
+    return JSON.parse(data) as Record<string, unknown> | unknown[];
+  } catch {
+    return data;
+  }
+}
+
+/**
+ * Try to parse a single field as a bare JSON **object or array** body.
+ *
+ * The `startsWith` guard is intentional — not just an optimisation.  It
+ * restricts detection to objects (`{`) and arrays (`[`), excluding JSON
+ * primitives like `42`, `true`, `"string"`.  Without this guard those
+ * primitives would be extracted as the body, and downstream code (e.g. the
+ * `k in body` key-conflict check) would throw a `TypeError` because the `in`
+ * operator requires an object on the right-hand side.
+ *
+ * @internal
+ */
+function tryParseJsonField(
+  field: string
+): Record<string, unknown> | unknown[] | undefined {
+  if (field.includes("=")) {
+    return;
+  }
+  if (!(field.startsWith("{") || field.startsWith("["))) {
+    return;
+  }
+
+  try {
+    return JSON.parse(field) as Record<string, unknown> | unknown[];
+  } catch {
+    return;
+  }
+}
+
+/**
+ * Scan a field list for bare JSON **object or array** values (no `=`) and
+ * extract the first one as the intended request body.  This handles the
+ * common mistake of passing `-f '{"status":"ignored"}'` instead of
+ * `-d '{"status":"ignored"}'`.
+ *
+ * Detection is conservative: the field must have no `=`, start with `{` or
+ * `[`, and parse as valid JSON.  Only one JSON body is allowed — multiple
+ * JSON fields are ambiguous and produce a {@link ValidationError}.
+ *
+ * @returns An object with the extracted `body` (if any) and the `remaining`
+ *   fields that are normal key=value entries, or `undefined` if the input
+ *   was empty/undefined.
+ * @internal Exported for testing
+ */
+export function extractJsonBody(
+  fields: string[] | undefined,
+  stderr: Writer
+): { body?: Record<string, unknown> | unknown[]; remaining?: string[] } {
+  if (!fields || fields.length === 0) {
+    return {};
+  }
+
+  let jsonBody: Record<string, unknown> | unknown[] | undefined;
+  const remaining: string[] = [];
+
+  for (const field of fields) {
+    const parsed = tryParseJsonField(field);
+
+    if (parsed === undefined) {
+      remaining.push(field);
+      continue;
+    }
+
+    if (jsonBody !== undefined) {
+      throw new ValidationError(
+        "Multiple JSON bodies detected in field arguments. " +
+          "Use --data/-d to pass an inline JSON body explicitly.",
+        "field"
+      );
+    }
+
+    jsonBody = parsed;
+    const preview = field.length > 60 ? `${field.substring(0, 57)}...` : field;
+    stderr.write(
+      `hint: '${preview}' was used as the request body. ` +
+        "Use --data/-d to pass inline JSON next time.\n"
+    );
+  }
+
+  return {
+    body: jsonBody,
+    remaining: remaining.length > 0 ? remaining : undefined,
+  };
+}
+
 /**
  * Build request body from --input flag (file or stdin).
  * Tries to parse the content as JSON, otherwise returns as string.
@@ -766,6 +877,119 @@ export function handleResponse(
   }
 }
 
+/**
+ * Build body and params from field flags, auto-detecting bare JSON bodies.
+ *
+ * Runs colon-to-equals normalization, extracts any JSON body passed as a
+ * field value (with a stderr hint about `--data`), and routes the remaining
+ * fields to body or query params based on the HTTP method.
+ *
+ * @internal Exported for testing
+ */
+export function buildFromFields(
+  method: HttpMethod,
+  flags: Pick<ApiFlags, "field" | "raw-field">,
+  stderr: Writer
+): {
+  body?: Record<string, unknown> | unknown[];
+  params?: Record<string, string | string[]>;
+} {
+  const field = normalizeFields(flags.field, stderr);
+  let rawField = normalizeFields(flags["raw-field"], stderr);
+
+  // Auto-detect bare JSON passed as a field value (common mistake).
+  // GET requests don't have a body — skip detection so JSON-shaped values
+  // fall through to query-param routing (which will throw a clear error).
+  let body: Record<string, unknown> | unknown[] | undefined;
+  if (method !== "GET") {
+    const extracted = extractJsonBody(rawField, stderr);
+    body = extracted.body;
+    rawField = extracted.remaining;
+  }
+
+  // Route remaining fields to body (merge) or params based on HTTP method
+  const options = prepareRequestOptions(method, field, rawField);
+  if (options.body) {
+    if (Array.isArray(body)) {
+      // Can't meaningfully merge key=value fields into a JSON array body.
+      throw new ValidationError(
+        "Cannot combine a JSON array body with field flags (-F/-f). " +
+          "Use --data/-d to pass the array as the full body without extra fields.",
+        "field"
+      );
+    }
+    if (body) {
+      // Detect top-level key conflicts before merging — a shallow spread would
+      // silently drop nested fields from the JSON body (e.g. statusDetails.ignoreCount
+      // overwritten by statusDetails[minCount]=5).
+      const conflicts = Object.keys(options.body).filter(
+        (k) => k in (body as Record<string, unknown>)
+      );
+      if (conflicts.length > 0) {
+        throw new ValidationError(
+          `Field flag(s) conflict with detected JSON body at key(s): ${conflicts.join(", ")}. ` +
+            "Use --data/-d to pass the full JSON body, or use only field flags (-F/-f).",
+          "field"
+        );
+      }
+    }
+    // Merge field-built key=value entries into the auto-detected JSON object body
+    body =
+      body && typeof body === "object"
+        ? { ...(body as Record<string, unknown>), ...options.body }
+        : options.body;
+  }
+
+  return { body, params: options.params };
+}
+
+/**
+ * Resolve the request body and query params from the user-provided flags.
+ *
+ * Priority order: `--data` > `--input` > field flags (`-F`/`-f`).
+ * Mutually-exclusive combinations throw {@link ValidationError}.
+ *
+ * @returns body and params ready for the API request
+ * @internal Exported for testing
+ */
+export async function resolveBody(
+  flags: Pick<ApiFlags, "method" | "data" | "input" | "field" | "raw-field">,
+  stdin: NodeJS.ReadStream & { fd: 0 },
+  stderr: Writer
+): Promise<{
+  body?: Record<string, unknown> | unknown[] | string;
+  params?: Record<string, string | string[]>;
+}> {
+  if (flags.data !== undefined && flags.input !== undefined) {
+    throw new ValidationError(
+      "Cannot use --data and --input together. " +
+        "Use --data/-d for inline JSON, or --input for file/stdin.",
+      "data"
+    );
+  }
+
+  if (
+    flags.data !== undefined &&
+    (flags.field?.length || flags["raw-field"]?.length)
+  ) {
+    throw new ValidationError(
+      "Cannot use --data with --field or --raw-field. " +
+        "Use --data/-d for a full JSON body, or -F/-f for individual fields.",
+      "data"
+    );
+  }
+
+  if (flags.data !== undefined) {
+    return { body: parseDataBody(flags.data) };
+  }
+
+  if (flags.input !== undefined) {
+    return { body: await buildBodyFromInput(flags.input, stdin) };
+  }
+
+  return buildFromFields(flags.method, flags, stderr);
+}
+
 // Command Definition
 
 export const apiCommand = buildCommand({
@@ -775,6 +999,9 @@ export const apiCommand = buildCommand({
       "Make a raw API request to the Sentry API. Similar to 'gh api' for GitHub. " +
       "The endpoint is relative to /api/0/ (do not include the prefix). " +
       "Authentication is handled automatically using your stored credentials.\n\n" +
+      "Body options:\n" +
+      '  --data/-d \'{"key":"value"}\'   Inline JSON body (like curl -d)\n' +
+      '  --input/-i file.json          Read body from file (or "-" for stdin)\n\n' +
       "Field syntax (--field/-F):\n" +
       "  key=value          Simple field (values parsed as JSON if valid)\n" +
       "  key[sub]=value     Nested object: {key: {sub: value}}\n" +
@@ -784,6 +1011,7 @@ export const apiCommand = buildCommand({
       "Examples:\n" +
       "  sentry api organizations/\n" +
       "  sentry api issues/123/ -X PUT -F status=resolved\n" +
+      '  sentry api issues/123/ -X PUT -d \'{"status":"resolved"}\'\n' +
       "  sentry api projects/my-org/my-project/ -F options[sampleRate]=0.5\n" +
       "  sentry api teams/my-org/my-team/members/ -F user[email]=user@example.com",
   },
@@ -806,6 +1034,13 @@ export const apiCommand = buildCommand({
         default: "GET" as const,
         placeholder: "method",
       },
+      data: {
+        kind: "parsed",
+        parse: String,
+        brief: "Inline JSON body for the request (like curl -d)",
+        optional: true,
+        placeholder: "json",
+      },
       field: {
         kind: "parsed",
         parse: String,
@@ -853,6 +1088,7 @@ export const apiCommand = buildCommand({
     },
     aliases: {
       X: "method",
+      d: "data",
       F: "field",
       f: "raw-field",
       H: "header",
@@ -869,25 +1105,8 @@ export const apiCommand = buildCommand({
     // Normalize endpoint to ensure trailing slash (Sentry API requirement)
     const normalizedEndpoint = normalizeEndpoint(endpoint);
 
-    // Build request body/params from --input, --field, or --raw-field
-    // --input takes precedence; otherwise route fields based on HTTP method
-    let body: Record<string, unknown> | string | undefined;
-    let params: Record<string, string | string[]> | undefined;
-
-    if (flags.input !== undefined) {
-      // --input takes precedence for body content
-      body = await buildBodyFromInput(flags.input, stdin);
-    } else {
-      // Auto-correct ':'-separated fields (e.g. -F status:resolved → -F status=resolved)
-      // before routing to body or params so the correction applies everywhere.
-      const field = normalizeFields(flags.field, stderr);
-      const rawField = normalizeFields(flags["raw-field"], stderr);
-
-      // Route fields to body or params based on HTTP method
-      const options = prepareRequestOptions(flags.method, field, rawField);
-      body = options.body;
-      params = options.params;
-    }
+    // Resolve body and query params from flags (--data, --input, or fields)
+    const { body, params } = await resolveBody(flags, stdin, stderr);
 
     const headers =
       flags.header && flags.header.length > 0