sentry-cli

用途

Sentry CLI 用于从命令行与 Sentry 交互，帮助用户查看问题、事件、项目、组织、追踪、日志、发布等信息。它面向需要在终端或自动化流程中操作 Sentry 的用户，也包含面向 AI 编码代理的使用指引。

主要能力

问题排查：列出、查看、解释和规划问题修复。
追踪与性能：列出追踪、查看追踪的 span 树、查看 span 与关联日志。
日志：实时流式查看日志，并按严重级别过滤。
本地事件捕获（Spotlight）：在本地运行应用并捕获错误、追踪、日志，无需 DSN 即可只发送到本地服务器。
文档查询：通过 sentry docs 直接查询 Sentry 文档。
API 探索：通过 sentry schema 浏览或搜索 API 端点。
发布管理：创建发布、关联提交、标记完成、记录部署。
智能体会话：列出和查看智能体对话记录。
WebAssembly 模块处理：为 wasm 模块添加构建 ID、拆分调试数据。
任意 API 访问：通过 sentry api 以类似 curl 的方式直接调用接口。
仪表盘：以 6 列网格布局添加小组件，支持多种显示类型与数据集。

使用方式

核心规则是直接运行命令。CLI 会自动检测组织与项目（来自 .sentryclirc 配置、.env 或源码中的 DSN、以及目录名），因此不要先列出组织再列出项目来手动确定当前检出对应的项目。仅当 CLI 报告无法检测目标或检测错误时，才显式传入 <org>/<project>。

命令遵循 gh（GitHub CLI）的 <名词> <动词> 模式，例如 sentry issue list、sentry org view。标志也沿用 gh 约定：--json 输出机器可读结果，--fields 选择特定字段，-w/--web 在浏览器中打开，-q/--query 过滤，-n/--limit 限制结果数量。sentry api 命令模仿 curl，提供 --method、--data、--header 等选项并自动处理认证。

常用工作流示例：

排查问题：

sentry issue list --query "is:unresolved" --limit 5
sentry issue view PROJECT-123 --json
sentry issue explain PROJECT-123
sentry issue plan PROJECT-123

探索追踪与性能：

sentry trace list --limit 5
sentry trace view abc123def456...
sentry span list abc123def456...
sentry trace logs abc123def456...

流式查看日志：

sentry log list --follow
sentry log list --query "severity:error"

本地捕获事件（Spotlight）：

sentry local run -- npm run dev
sentry local run --open -- npm run dev
sentry local -f ai

查询文档与状态：

sentry docs "How do I configure tracing in Next.js?"
sentry docs list "source maps"
sentry status
sentry status --json

探索 API：

sentry schema
sentry schema issues
sentry schema "GET /api/0/organizations/{organization_id_or_slug}/issues/"

管理发布：

sentry release create my-org/1.0.0 --project my-project
sentry release set-commits my-org/1.0.0 --auto
sentry release set-commits my-org/1.0.0 --local
sentry release finalize my-org/1.0.0
sentry release deploy my-org/1.0.0 production

查看智能体会话：

sentry agent-conversation list
sentry agent-conversation list my-org --period 24h
sentry agent-conversation view my-org/conv-123
sentry agent-conversation view conv-123 --json

处理 WebAssembly 模块：

sentry wasm-split app.wasm
BUILD_ID=$(sentry wasm-split app.wasm)
sentry wasm-split app.wasm --debug-out app.debug.wasm --strip

任意 API 访问：

sentry api /api/0/organizations/my-org/
sentry api /api/0/organizations/my-org/projects/ --method POST --data '{"name":"new-project","platform":"python"}'

适用场景

在终端中快速排查 Sentry 问题与事件。
分析追踪、span 与性能数据。
实时查看日志并按严重级别过滤。
在本地开发时捕获事件而不消耗生产配额。
在 CI 或脚本中管理发布与部署。
查询 Sentry 文档与 API 结构。
查看智能体对话记录。
处理 WebAssembly 调试数据。

限制与注意事项

使用前必须安装并认证 CLI。
破坏性命令（如 project delete、trial start）必须先与用户确认。
变更操作前应确认命令输出中的组织/项目上下文正确。
不得存储或记录认证令牌，CLI 会自动管理凭据。
若 CLI 报告组织/项目错误，用显式 <org>/<project> 参数覆盖。
问题 ID 应使用短 ID（如 PROJECT-123），而非数字 ID。
程序化解析输出时应使用 --json。
--query 使用 Sentry 搜索语法（如 is:unresolved、assigned:me），不是自由文本搜索。
发布版本必须与 Sentry.init() 中的 release 值完全一致，位置参数为 <org-slug>/<version>。
--auto 需要 Sentry 仓库集成与本地 git 检出；无检出时使用 --local。
退出码具有语义：0 成功，10–19 认证错误，20–29 输入错误，30–39 API 错误，40–49 功能不可用，50–59 操作错误，60–69 命令特定错误。
仪表盘使用 6 列网格，添加小组件时应填满整行。
可用数据集包括 spans（默认）、errors、metrics、issue、logs；Events API 的有效数据集值为 spans、logs、errors、tracemetrics、profile_functions、uptime_results。
具体安装方式、收费与价格信息暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项