feat: add `sentry schema` command for API introspection by BYK · Pull Request #437 · getsentry/cli

BYK · 2026-03-16T19:52:14Z

Phase 2 of #346: Add sentry schema command for runtime API introspection by AI agents.

What

Enables AI agents to discover Sentry API endpoints at runtime without pre-loaded documentation:

sentry schema                        # List all API resources with endpoint counts
sentry schema issues                 # Endpoints for 'issues' resource
sentry schema issues retrieve        # Detailed endpoint info (method, path, params, description)
sentry schema issues retrieve --json # Machine-readable output
sentry schema -q replay              # Search across all endpoints
sentry schema --all                  # Flat list of all 215 endpoints
sentry schema 'monitor*'             # Glob pattern matching on resources

Architecture

Build-time generation — script/generate-api-schema.ts fetches the dereferenced OpenAPI spec from getsentry/sentry-api-schema (version-tagged to match the installed @sentry/api package) and extracts:

HTTP methods and URL templates from the OpenAPI paths
Human-readable descriptions and deprecation status
Query parameter names from OpenAPI parameter definitions
SDK function name mapping from the @sentry/api JS bundle
Resource names derived from URL paths (last non-parameter segment)

Output: src/generated/api-schema.json (215 endpoints, ~117KB) — gitignored, generated at build/dev/test time via bun run generate:schema.

Runtime — src/lib/api-schema.ts provides query functions:

getResourceSummaries() — grouped resource overview
getEndpointsByResource() — filter by resource
getEndpoint() — find specific endpoint (prefers operationId prefix match)
searchEndpoints() — full-text search across all fields
Glob pattern support via regex conversion for resource matching

The sentry schema command yields CommandOutput through the standard output system with mdKvTable + renderMarkdown for endpoint detail views.

Other changes

Updated @sentry/api from 0.21.0 → 0.54.0
CI workflow updated to run generate:schema before lint, typecheck, and tests
src/generated/ added to .gitignore

Tests

19 unit tests for schema query functions covering all query modes, edge cases, and data invariants.

github-actions · 2026-03-16T19:52:35Z

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

New Features ✨

Init

Show feedback hint after successful setup by betegon in #430
Add --team flag to relay team selection to project creation by MathurAditya724 in #403
Enforce canonical feature display order by betegon in #388
Accept multiple delimiter formats for --features flag by betegon in #386
Add git safety checks before wizard modifies files by betegon in #379
Add experimental warning before wizard runs by betegon in #378
Add init command for guided Sentry project setup by betegon in #283

Issue List

Auto-compact when table exceeds terminal height by BYK in #395
Redesign table to match Sentry web UI by BYK in #372

Other

(auth) Allow re-authentication without manual logout by BYK in #417
(trial) Auto-prompt for Seer trial + sentry trial list/start commands by BYK in #399

Add sentry schema command for API introspection by BYK in #437

Add --json flag to help command for agent introspection by BYK in #432
Add sentry span list and sentry span view commands by betegon in #393
Support SENTRY_HOST as alias for SENTRY_URL by betegon in #409
Add --dry-run flag to mutating commands by BYK in #387
Return-based output with OutputConfig on buildCommand by BYK in #380
Add --fields flag for context-window-friendly JSON output by BYK in #373
Magic @ selectors (@latest, @most_frequent) for issue commands by BYK in #371
Input hardening against agent hallucinations by BYK in #370
Add response caching for read-only API calls by BYK in #330

Bug Fixes 🐛

Dsn

Make code scanner monorepo-aware and extend --fresh to bypass DSN cache by betegon in #420
Prevent silent exit during uncached DSN auto-detection (Bug: Process exits silently with no output when DSN auto-detection is slow (uncached first run) #411) by BYK in #414

Init

Align multiselect hint lines with clack's visual frame by MathurAditya724 in #435
Make URLs clickable with OSC 8 terminal hyperlinks by MathurAditya724 in #423
Remove implementation detail from help text by betegon in #385
Truncate uncommitted file list to first 5 entries by MathurAditya724 in #381

Other

(api) Convert --data to query params for GET requests by BYK in #383
(docs) Remove double borders and fix column alignment on landing page tables by betegon in #369
(trace) Show span IDs in trace view and fix event_id mapping by betegon in #400
Show human-friendly names in trial list and surface plan trials by BYK in #412
Add trace ID validation to trace view + UUID dash-stripping by BYK in #375

Documentation 📚

Update AGENTS.md with patterns from span commands work by BYK in #433
Update credential storage docs and remove stale config.json references by betegon in #408

Internal Changes 🔧

Init

Remove --force flag by betegon in #377
Remove dead determine-pm step label by betegon in #374

Tests

Consolidate unit tests subsumed by property tests by BYK in #422
Remove redundant and low-value tests by BYK in #418

Other

(lint) Enforce command output conventions via Biome plugins by BYK in #439
(log/list) Convert non-follow paths to return CommandOutput by BYK in #410
Unified trace-target parsing and resolution by BYK in #438
Centralize slug normalization warning in parseOrgProjectArg by BYK in #436
Unify commands as generators with HumanRenderer factory, remove stdout plumbing by BYK in #416
Convert list command handlers to return data instead of writing stdout by BYK in #404
Split api-client.ts into focused domain modules by BYK in #405
Migrate non-streaming commands to CommandOutput with markdown rendering by BYK in #398
Convert Tier 2-3 commands to return-based output and consola by BYK in #394
Convert remaining Tier 1 commands to return-based output by BYK in #382
Converge Tier 1 commands to writeOutput helper by BYK in #376

Other

Minify JSON on read and pretty-print on write in init local ops by MathurAditya724 in #396

_{🤖 This preview updates automatically when you update the PR.}

github-actions · 2026-03-16T19:53:56Z

Codecov Results 📊

✅ 111 passed | Total: 111 | Pass Rate: 100% | Execution Time: 0ms

📊 Comparison with Base Branch

Metric	Change
Total Tests	—
Passed Tests	—
Failed Tests	—
Skipped Tests	—

✨ No test changes detected

All tests are passing successfully.

✅ Patch coverage is 100.00%. Project has 1101 uncovered lines.
✅ Project coverage is 95.09%. Comparing base (base) to head (head).

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    95.06%    95.09%    +0.03%
==========================================
  Files          165       167        +2
  Lines        22299     22406      +107
  Branches         0         0         —
==========================================
+ Hits         21198     21305      +107
- Misses        1101      1101         —
- Partials         0         0         —

Generated by Codecov Action

script/generate-api-schema.ts

BYK · 2026-03-16T20:07:14Z

Addressing review comments

require.resolve — Now using require.resolve('@sentry/api/package.json') to locate the package instead of hardcoded node_modules path.
OpenAPI spec instead of JS parsing — Rewrote the generator to fetch the dereferenced OpenAPI spec from getsentry/sentry-api-schema. The version tag is derived from the installed @sentry/api package version (now 0.54.0). This gives us:
- Proper operationId from the spec (e.g., "List an Organization's Issues")
- Query parameters extracted from OpenAPI parameter definitions
- Accurate deprecation flags from the spec
- No fragile regex parsing of JS bundles
The SDK function name mapping is still extracted from @sentry/api's bundled JS (to map operationIds to their TypeScript function names), but this is a secondary lookup — the primary data comes from the OpenAPI spec.
Updated @sentry/api from 0.21.0 → 0.54.0 to match the latest schema.

src/commands/schema.ts

src/lib/api-schema.ts

src/commands/schema.ts

src/lib/api-schema.ts

BYK · 2026-03-16T20:56:40Z

Round 3 review fixes

All six comments addressed:

mdKvTable + renderMarkdown for endpoint detail — Replaced manual string building with mdKvTable key-value rows (Resource, Operation, Function, Status, Path Params, Query Params) rendered through the markdown pipeline.
Renamed --list → --all — Flag now called --all for showing flat endpoint list.
Fixed padding before color formatting — Color is now applied to the raw method string, then spaces are appended outside the ANSI escape codes.
Empty array guard in formatResourceList — Returns early with "No resources found." before Math.max call on empty arrays.
Added -q alias for --search — Can now use sentry schema -q monitor as shorthand.
Glob-style search — Positional args containing * or ? are treated as glob patterns via Bun.Glob. Example: sentry schema monitor* matches resources starting with "monitor".

Re: fuzzy/levenshtein — there's a private levenshtein() in platforms.ts but it's not exported. Extracting it to a shared module is a good follow-up but out of scope for this PR. The substring + glob search covers the primary use cases.

src/commands/schema.ts

src/lib/api-schema.ts

script/generate-api-schema.ts

src/commands/schema.ts

script/generate-api-schema.ts

src/commands/schema.ts

package.json

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

src/lib/api-schema.ts

Phase 2 of #346: Add `sentry schema` command for runtime API introspection by AI agents. New features: - `sentry schema` — list all API resources with endpoint counts - `sentry schema <resource>` — list endpoints for a resource - `sentry schema <resource> <operation>` — show endpoint details - `sentry schema --list` — flat list of all 214 API endpoints - `sentry schema --search <query>` — search across endpoints - All modes support `--json` for machine-readable output Architecture: - `script/generate-api-schema.ts` — build-time parser that extracts endpoint metadata from `@sentry/api` (function names, HTTP methods, URL templates, JSDoc descriptions, deprecation status) - `src/generated/api-schema.json` — lightweight index (102KB, 214 endpoints) bundled into the CLI - `src/lib/api-schema.ts` — runtime query functions (by resource, operation, or full-text search) - `src/commands/schema.ts` — command with human + JSON output modes Tests: 19 unit tests for schema query functions

script/generate-api-schema.ts

BYK commented Mar 16, 2026

View reviewed changes

script/generate-api-schema.ts Outdated Show resolved Hide resolved

script/generate-api-schema.ts Show resolved Hide resolved

BYK force-pushed the feat/schema-command branch from 2c58186 to 1dad125 Compare March 16, 2026 20:07

BYK marked this pull request as ready for review March 16, 2026 20:24