Sentry CLI 是 Sentry 官方的命令行工具，用于从命令行与 Sentry 交互。本技能文档面向使用该 CLI 的用户与 AI coding agent，介绍其命令、约定与实践建议。
用途 主要用于在终端中查看和操作 Sentry 资源：问题（issue）、事件、项目、组织、追踪（trace）、span、日志、发布（release）、agent 对话等，也支持查询 Sentry 文档、查看服务状态、浏览 API schema，以及发起任意 API 请求。
核心原则 使用 agent 时直接运行命令即可。CLI 会自动检测组织与项目，来源包括 .sentryclirc 配置文件、.env 或源码中的 DSN、以及目录名。因此不要先列出组织再列出各自项目来推断当前检出对应哪个项目，这种手工发现只是重复 CLI 每条命令内部已做的事。只有当 CLI 报告无法检测目标或检测错误时，才显式传入 <org>/<project>。
CLI 会在需要时提示登录；不必每次命令前预先认证。优先使用 CLI 专用命令，而不是直接调用 API。
设计约定 命令遵循 <noun> <verb> 模式（如 sentry issue list、sentry org view），参数风格参考 gh（GitHub CLI）：--json 输出机器可读格式，--fields 选择字段，-w/--web 在浏览器打开，-q/--query 过滤，-n/--limit 限制结果数。sentry api 命令模仿 curl：--method 指定 HTTP 方法，--data 传请求体，--header 传自定义头，并自动处理认证。
上下文窗口建议 使用 --json --fields 选择特定字段以减小输出体积；用 <command> --help 查看可用字段。在命令间传递或程序化处理时使用 --json。用 --limit 限制结果数。优先用 sentry issue view PROJECT-123 而非列表后手工过滤。一次调用传入多个 issue ID，而不是逐个循环。用 sentry api 处理专用命令未覆盖的端点。
安全规则 执行破坏性命令前（如 project delete、trial start）必须与用户确认。对变更类操作，先确认输出中的 org/project 上下文正确再继续。不要存储或记录认证令牌。若 CLI 报告组织/项目错误，用显式 <org>/<project> 覆盖。
退出码 0 成功；10–19 认证错误（提示用户运行 sentry auth login）；20–29 输入错误；30–39 API 错误；40–49 功能不可用；50–59 操作错误；60–69 命令特定错误，查看 stderr。
典型工作流 排查 issue：用 sentry issue list --query "is:unresolved" --limit 5 查找，再用 sentry issue view PROJECT-123 --json 获取详情（agent 优先用 --json，其中包含完整 issue 及最新事件），随后可用 sentry issue explain PROJECT-123 获取 AI 根因分析、sentry issue plan PROJECT-123 获取修复计划。可用 --fields 选择字段，避免拉取完整 request/session 数据。
追踪与性能：sentry trace list、sentry trace view、sentry span list、sentry trace logs。
日志：sentry log list --follow 实时流式查看，--query "severity:error" 过滤。
本地捕获（Spotlight）：sentry local run -- npm run dev 可启用本地服务器并 tail 错误/追踪/日志，无需 DSN 时事件只发往本地服务器；sentry local -f ai 仅观察 AI/agent（gen_ai、mcp）span。
文档与 API：sentry docs "问题" 查询文档，sentry docs list "source maps" 搜索索引；sentry schema 浏览 API 资源类别或搜索端点。sentry status 查看服务状态。
发布管理：sentry release create <org-slug>/<version> --project <project>；sentry release set-commits 支持 --auto（需仓库集成与本地 git 检出）或 --local；sentry release finalize 标记发布完成；sentry release deploy 记录部署。版本号必须与 Sentry.init() 中的 release 完全一致，org 与 version 用斜杠分隔。
其他能力 sentry agent-conversation list/view 查看 agent 对话及其转录；sentry wasm-split 为 WebAssembly 模块添加 build id 或拆分调试数据（无需认证）；sentry api 发起任意 API 请求。Dashboard 使用 6 列网格，提供 big_number、line、area、bar、table 等显示类型及默认尺寸，可用 sentry dashboard widget 添加组件。
常见错误 issue ID 应使用 PROJECT-123 短 ID，而非纯数字 ID；不必每条命令前预先认证；程序化解析需加 --json；不必要地指定 org/project；手工发现项目；混淆 --query 语法（使用 Sentry 搜索语法如 is:unresolved、assigned:me）；未使用 --web；外部抓取 API schema 或文档；release 版本与 Sentry.init() 不一致或双重前缀；在无 git 检出时使用 set-commits --auto；在 CLI 命令已足够时使用 sentry api。
前置条件 使用前必须安装并认证 CLI。安装方式与具体认证步骤暂未提供。