Add `schema` subcommand for runtime API introspection by agents

[sentry-junior]

Add a schema subcommand for runtime API introspection by agents

The Sentry CLI currently ships static documentation and help text optimized for human consumption. As AI agents increasingly use CLIs as their primary interface to external systems, this model breaks down: baked-in docs go stale, and stuffing full API documentation into an agent system prompt is token-expensive.

A better pattern: make the CLI itself the documentation, queryable at runtime.

Current behavior

There is no machine-readable way to introspect the Sentry API schema from the CLI at runtime. Agents consuming sentry-cli must rely on static docs, pre-loaded system prompt context, or direct Sentry API calls — all of which are expensive in tokens or stale.

Gap

Agents self-serving schema information from the CLI would allow them to:

• Discover available parameters, request/response shapes, and required auth scopes on demand
• Avoid pre-stuffing full API documentation into their context window
• Always reflect the current API state rather than potentially-stale docs

The Sentry API already has a machine-readable schema surface (via the @sentry/api package and the OpenAPI spec). The CLI is the natural delivery mechanism.

Prior art

The Google Workspace CLI (gws) implements this pattern via gws schema <method>, which dumps full method signatures as JSON using the Google Discovery Document with dynamic $ref resolution.

"Each gws schema call dumps the full method signature — params, request body, response types, required OAuth scopes — as machine-readable JSON. The agent self-serves without pre-stuffed documentation."
— Justin Poehnelt, Google DevRel

Options

1. sentry schema <resource> <operation> — dump the resolved OpenAPI schema for a specific endpoint as JSON, powered by the existing @sentry/api OpenAPI spec. Minimal surface, high value.

2. sentry schema --list — enumerate all available resources/operations as a machine-readable index, enabling agents to discover what they can query before requesting a specific schema.

3. Both — ship --list for discovery and per-operation schema for detail. Likely the right end state; can ship incrementally.

Additional considerations

Machine-readable --help

Alongside or as a stepping stone to sentry schema, we should consider a --help --json mode (or sentry help --json <command>) that emits the Stricli command metadata as structured JSON. This is lower-effort than full OpenAPI introspection and immediately useful: an agent can discover flags, positional args, defaults, and brief descriptions for any command without parsing --help output.

We already introspect Stricli's route tree in script/generate-skill.ts — the same traversal logic can power a runtime --help --json.

CLI command schema vs API schema

There are two distinct but complementary surfaces:

• CLI command schema — what flags/args does sentry issue list accept? (Stricli metadata)
• API schema — what does GET /api/0/organizations/{organization_slug}/issues/ accept and return? (OpenAPI spec)

Option 1 gives agents API-level introspection. --help --json gives CLI-level introspection. Both are valuable; CLI schema is likely cheaper to ship first.

Context window efficiency

As Justin's article notes: "Static API documentation baked into a system prompt is expensive in tokens and goes stale." Schema introspection lets agents pull only the schema fragment they need for the current task, rather than front-loading everything.

Recommendation

Ship in two phases:

1. Phase 1: sentry help --json [command] — emit Stricli command metadata as JSON. Low effort, high value, no external dependencies.
2. Phase 2: sentry schema <resource> <operation> — full OpenAPI schema fragments from @sentry/api. Higher effort, covers the sentry api raw-request use case.

Output should always be JSON (this is a machine-first feature).

References

• You Need to Rewrite Your CLI for AI Agents — Justin Poehnelt
• Existing issue: Use Sentry's OpenAPI schema as source of truth for API interactions #88 (Use Sentry's OpenAPI schema as source of truth)
• script/generate-skill.ts — existing Stricli route tree introspection