feat: add --fields flag for context-window-friendly JSON output (#373)

## Summary

Add a `--fields` flag to all 14 commands that support `--json` output,
allowing agents (and humans) to request only specific fields. This
reduces token consumption and keeps agent context windows focused.

Fixes #347

## Motivation

From [You Need to Rewrite Your CLI for AI
Agents](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/):

> "APIs return massive blobs. A single Gmail message can consume a
meaningful fraction of an agent's context window. Humans don't care —
humans scroll. **Agents pay per token and lose reasoning capacity with
every irrelevant field.**"

A full `sentry issue view --json` dumps the entire issue object, latest
event, and span tree. An agent that just needs `id`, `title`, and
`status` is forced to ingest thousands of tokens of irrelevant data.

## Usage

```bash
# Select specific top-level fields
sentry issue list --json --fields id,shortId,title,status

# Dot-notation for nested fields
sentry issue view --json --fields id,title,metadata.value

# Works with all --json commands
sentry event view --json --fields eventID,dateCreated,contexts.trace
sentry project list --json --fields slug,platform
```

## Design

**Option A from the issue**: Simple `--fields` flag with comma-separated
field paths. Covers the 90% case for agents, trivial to implement, no
external dependencies.

### Core implementation (`src/lib/formatters/json.ts`)
- `filterFields(data, fields)` — picks specified fields from
objects/arrays, supports dot-notation for nested access, silently skips
missing fields
- `parseFieldsList(input)` — parses comma-separated input with dedup,
whitespace trimming, empty segment filtering
- `writeJson(stream, data, fields?)` — optional `fields` param filters
output before serialization

### Shared flag (`src/lib/list-command.ts`)
- `FIELDS_FLAG` — Stricli flag constant shared by all commands with
`--json`

### Commands updated (14 total)
`auth whoami`, `event view`, `issue explain`, `issue list`, `issue
plan`, `issue view`, `log list`, `log view`, `org list`, `project
create`, `project list`, `project view`, `trace list`, `trace view`

## Edge cases
- Empty fields array → outputs full object (no filtering)
- Missing fields → silently ignored (no errors)
- Dot-notation with null/primitive intermediaries → skipped
- Array data → each element filtered independently
- Primitive data (string, number) → passed through unchanged
- Keys containing dots → inherent dot-notation ambiguity (documented
limitation)
- `--fields` without `--json` → silently ignored

## Testing

- **12 property-based tests** — identity, subset invariant, idempotency,
array mapping, deduplication, whitespace tolerance, round-trip
- **36 unit tests** — specific edge cases, dot-notation, integration
with writeJson
- All 3088 existing tests continue to pass (1 pre-existing failure in
log formatter)

---------

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

Author: BYK

AGENTS.md

@@ -74,8 +74,9 @@ sentry auth logout
 Refresh your authentication token
 
 **Flags:**
-- `--json - Output result as JSON`
 - `--force - Force refresh even if token is still valid`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -106,8 +107,9 @@ Print the stored authentication token
 Show the currently authenticated user
 
 **Flags:**
-- `--json - Output as JSON`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Org
 
@@ -119,8 +121,9 @@ List organizations
 
 **Flags:**
 - `-n, --limit <value> - Maximum number of organizations to list - (default: "30")`
-- `--json - Output JSON`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -135,9 +138,10 @@ sentry org list --json
 View details of an organization
 
 **Flags:**
-- `--json - Output as JSON`
 - `-w, --web - Open in browser`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -160,17 +164,19 @@ Create a new project
 **Flags:**
 - `-t, --team <value> - Team to create the project under`
 - `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 #### `sentry project list <org/project>`
 
 List projects
 
 **Flags:**
 - `-n, --limit <value> - Maximum number of projects to list - (default: "30")`
-- `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `-p, --platform <value> - Filter by platform (e.g., javascript, python)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -190,9 +196,10 @@ sentry project list --platform javascript
 View details of a project
 
 **Flags:**
-- `--json - Output as JSON`
 - `-w, --web - Open in browser`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -224,10 +231,11 @@ List issues in a project
 - `-n, --limit <value> - Maximum number of issues to list - (default: "25")`
 - `-s, --sort <value> - Sort by: date, new, freq, user - (default: "date")`
 - `-t, --period <value> - Time period for issue activity (e.g. 24h, 14d, 90d) - (default: "90d")`
-- `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor for <org>/ or multi-target modes (use "last" to continue)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
 - `--compact - Single-line rows for compact output`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -270,9 +278,10 @@ sentry issue list my-org/frontend --query "is:unresolved TypeError"
 Analyze an issue's root cause using Seer AI
 
 **Flags:**
-- `--json - Output as JSON`
 - `--force - Force new analysis even if one exists`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -298,9 +307,10 @@ Generate a solution plan using Seer AI
 
 **Flags:**
 - `--cause <value> - Root cause ID to plan (required if multiple causes exist)`
-- `--json - Output as JSON`
 - `--force - Force new plan even if one exists`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -325,10 +335,11 @@ sentry issue plan myproject-G --cause 0
 View details of a specific issue
 
 **Flags:**
-- `--json - Output as JSON`
 - `-w, --web - Open in browser`
 - `--spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -353,10 +364,11 @@ View Sentry events
 View details of a specific event
 
 **Flags:**
-- `--json - Output as JSON`
 - `-w, --web - Open in browser`
 - `--spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -477,9 +489,10 @@ List repositories
 
 **Flags:**
 - `-n, --limit <value> - Maximum number of repositories to list - (default: "30")`
-- `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Team
 
@@ -491,9 +504,10 @@ List teams
 
 **Flags:**
 - `-n, --limit <value> - Maximum number of teams to list - (default: "30")`
-- `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -523,8 +537,9 @@ List logs from a project
 - `-q, --query <value> - Filter query (Sentry search syntax)`
 - `-f, --follow <value> - Stream logs (optionally specify poll interval in seconds)`
 - `--trace <value> - Filter logs by trace ID (32-character hex string)`
-- `--json - Output as JSON`
 - `--fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -568,9 +583,10 @@ sentry log list my-org/backend -f -q 'level:error'
 View details of one or more log entries
 
 **Flags:**
-- `--json - Output as JSON`
 - `-w, --web - Open in browser`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -606,30 +622,33 @@ List recent traces in a project
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-s, --sort <value> - Sort by: date, duration - (default: "date")`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
-- `--json - Output as JSON`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 #### `sentry trace view <args...>`
 
 View details of a specific trace
 
 **Flags:**
-- `--json - Output as JSON`
 - `-w, --web - Open in browser`
 - `--spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 #### `sentry trace logs <args...>`
 
 View logs associated with a trace
 
 **Flags:**
-- `--json - Output as JSON`
 - `-w, --web - Open trace in browser`
 - `-t, --period <value> - Time period to search (e.g., "14d", "7d", "24h"). Default: 14d - (default: "14d")`
 - `-n, --limit <value> - Number of log entries (1-1000) - (default: "100")`
 - `-q, --query <value> - Additional filter query (Sentry search syntax)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Init
 
@@ -658,10 +677,11 @@ List issues in a project
 - `-n, --limit <value> - Maximum number of issues to list - (default: "25")`
 - `-s, --sort <value> - Sort by: date, new, freq, user - (default: "date")`
 - `-t, --period <value> - Time period for issue activity (e.g. 24h, 14d, 90d) - (default: "90d")`
-- `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor for <org>/ or multi-target modes (use "last" to continue)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
 - `--compact - Single-line rows for compact output`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Orgs
 
@@ -673,8 +693,9 @@ List organizations
 
 **Flags:**
 - `-n, --limit <value> - Maximum number of organizations to list - (default: "30")`
-- `--json - Output JSON`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Projects
 
@@ -686,10 +707,11 @@ List projects
 
 **Flags:**
 - `-n, --limit <value> - Maximum number of projects to list - (default: "30")`
-- `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `-p, --platform <value> - Filter by platform (e.g., javascript, python)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Repos
 
@@ -701,9 +723,10 @@ List repositories
 
 **Flags:**
 - `-n, --limit <value> - Maximum number of repositories to list - (default: "30")`
-- `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Teams
 
@@ -715,9 +738,10 @@ List teams
 
 **Flags:**
 - `-n, --limit <value> - Maximum number of teams to list - (default: "30")`
-- `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Logs
 
@@ -732,8 +756,9 @@ List logs from a project
 - `-q, --query <value> - Filter query (Sentry search syntax)`
 - `-f, --follow <value> - Stream logs (optionally specify poll interval in seconds)`
 - `--trace <value> - Filter logs by trace ID (32-character hex string)`
-- `--json - Output as JSON`
 - `--fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Traces
 
@@ -748,8 +773,9 @@ List recent traces in a project
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-s, --sort <value> - Sort by: date, duration - (default: "date")`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
-- `--json - Output as JSON`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ### Whoami
 
@@ -760,8 +786,9 @@ Show the currently authenticated user
 Show the currently authenticated user
 
 **Flags:**
-- `--json - Output as JSON`
 - `-f, --fresh - Bypass cache and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 ## Global Options
 

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

@@ -15,10 +15,12 @@ import {
 import { AuthError } from "../../lib/errors.js";
 import { success } from "../../lib/formatters/colors.js";
 import { formatDuration } from "../../lib/formatters/human.js";
+import { writeJson } from "../../lib/formatters/index.js";
 
 type RefreshFlags = {
   readonly json: boolean;
   readonly force: boolean;
+  readonly fields?: string[];
 };
 
 type RefreshOutput = {
@@ -50,13 +52,9 @@ Examples:
   {"success":true,"refreshed":true,"expiresIn":3600,"expiresAt":"..."}
     `.trim(),
   },
+  output: "json",
   parameters: {
     flags: {
-      json: {
-        kind: "boolean",
-        brief: "Output result as JSON",
-        default: false,
-      },
       force: {
         kind: "boolean",
         brief: "Force refresh even if token is still valid",
@@ -103,7 +101,7 @@ Examples:
     };
 
     if (flags.json) {
-      stdout.write(`${JSON.stringify(output)}\n`);
+      writeJson(stdout, output, flags.fields);
     } else if (result.refreshed) {
       stdout.write(
         `${success("✓")} Token refreshed successfully. Expires in ${formatDuration(result.expiresIn ?? 0)}.\n`