sentry plugin: CLI confusion and span aggregation gaps

[sentry-junior]

Summary

The sentry CLI at cli.sentry.dev (v0.16.0) is a fully capable tool with trace, span, issue, log commands — but it is easy to confuse with sentry-cli (the classic release/artifact tool), and its span querying capabilities have meaningful gaps that should be addressed in the plugin.

Background

When an agent attempted to count unique organizations with MCP tool call activity over a 30-day window, it bypassed the CLI and went straight to raw Sentry API calls. Two root causes:

1. Name collision with sentry-cli — The CLI at cli.sentry.dev is unrelated to the sentry-cli npm/binary tool that developers commonly know. Nothing in the plugin or documentation disambiguates these clearly.

2. sentry span list requires a trace ID — The command signature is sentry span list <org>/<project>/<trace-id>. There is no way to query spans across traces using attribute filters (e.g. has:mcp.tool.name) or to do aggregations (count distinct values, group-by). This is the primary reason the agent fell back to the raw EAP API endpoint.

3. sentry-mcp.md agent prompt does not reference the CLI — The sentry-mcp plugin's agent system prompt (plugins/sentry-mcp/agents/sentry-mcp.md) has no mention of the sentry CLI tool. Agents using the plugin have no signal that a CLI is available and what it can/cannot do.

4. Junior's CLI reference (cli-commands.md) is incomplete — The internal skill reference only documents issue, org, and common flags. Commands for trace, span, log, and event are absent, so the agent had no reason to try them.

Scope

• Disambiguate the sentry CLI from sentry-cli in docs/README — at minimum a callout box or note
• Add trace, span, log, and event command shapes to internal agent references
• Add span aggregation / cross-trace attribute search capability to the CLI (or document clearly that this must go through the raw EAP API)
• Consider adding a sentry span search subcommand that accepts arbitrary span attribute filters without requiring a trace ID, analogous to sentry issue list

Dependencies

The EAP spans API endpoint (/api/0/organizations/{org}/spans/) supports the aggregation query needed. The CLI would need to expose that surface, or the plugin docs should direct agents to the raw API for this class of query.

Action taken on behalf of David Cramer.