fix(cli): improve schema discovery

apps/cli-docs/src/content/docs/agent-guidance.md

@@ -10,7 +10,7 @@ Best practices and operational guidance for AI coding agents using the Sentry CL
 - **Just run the command** — the CLI handles authentication and org/project detection automatically. Don't pre-authenticate or look up org/project before running commands. The CLI prompts for login if needed.
 - **Prefer CLI commands over raw API calls** — the CLI has dedicated commands for most tasks. Reach for `sentry issue view`, `sentry issue list`, `sentry trace view`, etc. before constructing API calls manually or fetching external documentation.
 - **Use `sentry docs` for setup questions** — if you need to know how to configure a Sentry SDK or feature, run `sentry docs "your question"` to query the documentation directly. This is faster and more accurate than fetching docs externally.
-- **Use `sentry schema` to explore the API** — if you need to discover API endpoints, run `sentry schema` to browse interactively or `sentry schema <resource>` to search. This is faster than fetching OpenAPI specs externally.
+- **Use `sentry schema` to explore the API** — run `sentry schema` to list API resources or `sentry schema <query...>` to search by API concepts or CLI command paths. Use `sentry help <command>` for CLI flags and usage examples.
 - **Use `sentry issue view` to investigate issues** — when asked about a specific issue (e.g., `CLI-G5`, `PROJECT-123`), use `sentry issue view` directly. Multiple IDs can be passed in one invocation: `sentry issue view A B C --json` returns an array of the same objects.
 - **Use `--json` for machine-readable output** — pipe through `jq` for filtering. Human-readable output includes formatting that is hard to parse.
 - **The CLI auto-detects org/project — don't discover it yourself** — most commands work without explicit targets by checking `.sentryclirc` config files, scanning for DSNs in `.env` files and source code, and matching directory names. Do **not** run `sentry org list` and then `sentry project list` to figure out which project this checkout belongs to — that manual fan-out just replicates the detection the CLI already runs on every command. Only specify `<org>/<project>` when the CLI reports it can't detect the target or detects the wrong one.

apps/cli-docs/src/fragments/commands/schema.md

@@ -0,0 +1,19 @@
+Search the bundled API schema using product concepts or CLI command paths.
+Discovery includes summaries, paths, tags, and query parameter values: `logs`
+can find Explore's `dataset=logs` as well as feature-flag audit logs. Results
+explain their matches and show related CLI commands discovered from command
+implementations. A related API does not necessarily reproduce the command's filters,
+pagination, or transformations.
+
+Use `sentry help <command>` for CLI flags and usage examples. Schema describes
+API operations and parameters for constructing requests with `sentry api`.
+
+Use an exact operation ID, SDK function name, or HTTP method and path for a
+precise lookup. Concept searches return all matching candidates; deprecated
+operations are marked and sorted after active ones. No endpoint is chosen just
+because it appears first in the catalog.
+
+With `--json`, discovery returns an array of endpoints with additive `match`
+metadata. Exact single-endpoint lookups remain endpoint objects, `--search`
+always returns an array, and `--all` returns the flat catalog without match
+metadata. The schema is bundled from the CLI's SDK version and works offline.

packages/cli/DEVELOPMENT.md

@@ -102,6 +102,32 @@ pnpm run build
 
 ## Architecture
 
+### API discovery references
+
+`sentry schema` reads the index generated by `pnpm run generate:schema` from
+the installed `@sentry/api` version. New operations and query enum values become
+searchable when this index is regenerated; do not add a separate vocabulary map.
+The generator reads `@sentry/api/operations` directly, without fetching a schema
+or parsing the SDK bundle. The SDK owns operation metadata; the CLI preserves
+its resource grouping and JSON output format when projecting the catalog.
+
+`pnpm run generate:command-api` uses `@sentry/api/source-analysis` to follow command
+implementations and their helpers, generating API relationships from SDK calls
+and recognized raw request paths. The CLI supplies its command builders, request
+wrappers, and query context; it also reuses this analysis for DELETE checks.
+Keep dataset and filter values in the requests themselves; do not add a
+parallel list of operation names or command vocabulary. Build diagnostics report
+raw or unpublished calls that the generated catalog cannot identify, so the
+relationships describe discovered usage rather than exhaustive coverage.
+
+Introspection derives canonical command paths, registered aliases, and group
+membership from the route tree. Groups collect their public commands' generated
+references, so adding a command requires no separate group mapping. A related API
+does not reproduce the command's complete request orchestration, pagination, or
+transformations.
+
+### Authentication
+
 The CLI uses the OAuth 2.0 Device Authorization Grant ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) for authentication. This flow is designed for CLI tools and other devices that can't easily handle browser redirects:
 
 1. CLI requests a device code from Sentry

packages/cli/package.json

@@ -72,11 +72,12 @@
     "generate:sdk": "pnpm tsx script/generate-sdk.ts",
     "generate:skill": "pnpm tsx script/generate-skill.ts",
     "generate:banner": "pnpm tsx script/generate-banner-sixel.ts",
-    "generate:docs": "node script/ensure-generated.mjs schema && pnpm run generate:grammar && pnpm run generate:banner && pnpm run generate:completions && pnpm run generate:command-docs && pnpm run generate:docs-sections && pnpm run generate:skill",
+    "generate:docs": "node script/ensure-generated.mjs schema && pnpm run generate:grammar && pnpm run generate:command-api && pnpm run generate:banner && pnpm run generate:completions && pnpm run generate:command-docs && pnpm run generate:docs-sections && pnpm run generate:skill",
     "generate:grammar": "node ../../scripts/generate-parsers.mjs .",
     "generate:completions": "pnpm tsx script/generate-completion-targets.ts",
     "generate:docs-sections": "pnpm tsx script/generate-docs-sections.ts",
     "generate:schema": "pnpm tsx script/generate-api-schema.ts",
+    "generate:command-api": "pnpm tsx script/generate-command-api.ts",
     "generate:command-docs": "pnpm tsx script/generate-command-docs.ts",
     "eval:skill": "pnpm tsx script/eval-skill.ts",
     "bench": "pnpm tsx script/bench.ts",

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

@@ -22,7 +22,7 @@ Best practices and operational guidance for AI coding agents using the Sentry CL
 - **Just run the command** — the CLI handles authentication and org/project detection automatically. Don't pre-authenticate or look up org/project before running commands. The CLI prompts for login if needed.
 - **Prefer CLI commands over raw API calls** — the CLI has dedicated commands for most tasks. Reach for `sentry issue view`, `sentry issue list`, `sentry trace view`, etc. before constructing API calls manually or fetching external documentation.
 - **Use `sentry docs` for setup questions** — if you need to know how to configure a Sentry SDK or feature, run `sentry docs "your question"` to query the documentation directly. This is faster and more accurate than fetching docs externally.
-- **Use `sentry schema` to explore the API** — if you need to discover API endpoints, run `sentry schema` to browse interactively or `sentry schema <resource>` to search. This is faster than fetching OpenAPI specs externally.
+- **Use `sentry schema` to explore the API** — run `sentry schema` to list API resources or `sentry schema <query...>` to search by API concepts or CLI command paths. Use `sentry help <command>` for CLI flags and usage examples.
 - **Use `sentry issue view` to investigate issues** — when asked about a specific issue (e.g., `CLI-G5`, `PROJECT-123`), use `sentry issue view` directly. Multiple IDs can be passed in one invocation: `sentry issue view A B C --json` returns an array of the same objects.
 - **Use `--json` for machine-readable output** — pipe through `jq` for filtering. Human-readable output includes formatting that is hard to parse.
 - **The CLI auto-detects org/project — don't discover it yourself** — most commands work without explicit targets by checking `.sentryclirc` config files, scanning for DSNs in `.env` files and source code, and matching directory names. Do **not** run `sentry org list` and then `sentry project list` to figure out which project this checkout belongs to — that manual fan-out just replicates the detection the CLI already runs on every command. Only specify `<org>/<project>` when the CLI reports it can't detect the target or detects the wrong one.
@@ -806,7 +806,7 @@ Sentry for local development
 
 Browse the Sentry API schema
 
-- `sentry schema <resource...>` — Browse the Sentry API schema
+- `sentry schema <query...>` — Browse the Sentry API schema
 
 → Full flags and examples: `references/schema.md`
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/schema.md

@@ -11,15 +11,15 @@ requires:
 
 Browse the Sentry API schema
 
-### `sentry schema <resource...>`
+### `sentry schema <query...>`
 
 Browse the Sentry API schema
 
 **Arguments:**
 
 | Argument | Description |
 |----------|-------------|
-| `<resource...>` | Resource, exact operation ID, or METHOD /path |
+| `<query...>` | API concept, CLI command path, exact operation ID, or METHOD /path |
 
 **Flags:**
 - `--all - Show all endpoints in a flat list`
@@ -34,9 +34,21 @@ sentry schema
 # Browse issue endpoints
 sentry schema issues
 
-# View details for a specific operation
+# Find list operations (there may be multiple candidates)
 sentry schema issues list
 
+# Find APIs used by log listing
+sentry schema log list
+
+# Find APIs used by trace listing, including command aliases
+sentry schema trace ls
+
+# Find APIs used by a command group
+sentry schema alert metrics
+
+# Find APIs used by a nested command
+sentry schema alert metrics view
+
 # Look up an endpoint by its exact operation ID
 sentry schema listOrganizationEvents
 
@@ -46,6 +58,9 @@ sentry schema "GET /api/0/organizations/{organization_id_or_slug}/issues/"
 # Search for monitoring-related endpoints
 sentry schema --search monitor
 
+# Browse resources matching a glob
+sentry schema 'monitor*'
+
 # Flat list of every endpoint
 sentry schema --all
 ```