sentry-cli

Sentry CLI 使用指南

使用 sentry CLI 帮助用户通过命令行与 Sentry 交互。

Agent 指引

为使用 Sentry CLI 的 AI 编码 Agent 提供最佳实践和操作指引。

核心原则

• 直接运行命令——CLI 会自动处理身份验证以及组织/项目检测。运行命令前无需预先验证身份或查找组织/项目。如果需要身份验证，CLI 会以交互方式提示。
• 优先使用 CLI 命令，而非直接调用 API——CLI 为大多数任务提供了专用命令。应先尝试 sentry issue view、sentry issue list、sentry trace view 等命令，再手动构造 API 调用或获取外部文档。
• 使用 sentry schema 探索 API——如果需要查找 API 端点，可运行 sentry schema 进行交互式浏览，或运行 sentry schema <resource> 进行搜索。这比从外部获取 OpenAPI 规范更快。
• 使用 sentry issue view <id> 调查问题——如果用户询问特定问题（例如 CLI-G5、PROJECT-123），直接使用 sentry issue view。
• 使用 --json 获取机器可读的输出——可通过 jq 进行筛选。人类可读的输出包含难以解析的格式。
• CLI 会自动检测组织/项目——大多数命令无需指定目标；CLI 会检查 .sentryclirc 配置文件、扫描 .env 文件和源代码中的 DSN，并匹配目录名称。只有在 CLI 报告无法检测目标或检测到错误目标时，才指定 <org>/<project>。

设计原则

sentry CLI 遵循知名工具的惯例——如果你熟悉这些工具，可以直接运用相关知识：

• gh（GitHub CLI）惯例：sentry CLI 使用相同的 <noun> <verb> 命令模式（例如 sentry issue list、sentry org view）。标志遵循 gh 的惯例：使用 --json 获取机器可读的输出，使用 --fields 选择特定字段，使用 -w/--web 在浏览器中打开，使用 -q/--query 进行筛选，使用 -n/--limit 指定结果数量。
• sentry api 模仿 curl：sentry api 命令通过类似 curl 的接口直接访问 API——使用 --method 指定 HTTP 方法，使用 --data 指定请求正文，使用 --header 指定自定义标头。它会自动处理身份验证。如果你知道如何使用 curl 调用 REST API，也可以采用相同的模式。

上下文窗口提示

• 使用 --json --fields 选择特定字段，减少输出量。运行 <command> --help 查看可用字段。例如：sentry issue list --json --fields shortId,title,priority,level,status
• 在命令之间传递输出或以编程方式处理输出时，使用 --json
• 使用 --limit 限制结果数量（默认通常为 10–100）
• 优先使用 sentry issue view PROJECT-123，而不是手动列出并筛选
• 对于没有专用命令的端点，使用 sentry api

安全规则

• 运行破坏性命令前，务必先向用户确认：project delete、trial start
• 对于变更操作，继续进行其他更改前，先确认命令输出中的组织/项目上下文正确
• 切勿存储或记录身份验证令牌——CLI 会自动管理凭据
• 如果 CLI 报告的组织/项目有误，使用明确的 <org>/<project> 参数覆盖

退出代码

CLI 使用语义化退出代码。以下是 Agent 需要了解的主要范围：

范围	含义	Agent 操作
0	成功	正常继续
10–19	身份验证错误	提示用户运行 sentry auth login
20–29	输入错误	检查命令参数并重试
30–39	API 错误	重试或向用户报告
40–49	功能不可用	告知用户相关计划/设置
50–59	操作错误	向用户报告
60–69	命令特定错误	查看 stderr 获取详细信息

完整参考请参阅退出代码。

工作流模式

调查问题

# 1. Find the issue (auto-detects org/project from DSN or config)
sentry issue list --query "is:unresolved" --limit 5

# 2. Get details
sentry issue view PROJECT-123

# 3. Get AI root cause analysis
sentry issue explain PROJECT-123

# 4. Get a fix plan
sentry issue plan PROJECT-123

探索追踪和性能

# 1. List recent traces (auto-detects org/project)
sentry trace list --limit 5

# 2. View a specific trace with span tree
sentry trace view abc123def456...

# 3. View spans for a trace
sentry span list abc123def456...

# 4. View logs associated with a trace
sentry trace logs abc123def456...

流式日志

# Stream logs in real-time (auto-detects org/project)
sentry log list --follow

# Filter logs by severity
sentry log list --query "severity:error"

在本地捕获事件（Spotlight）

# Run the app with the local server auto-enabled; tail errors/traces/logs.
# No DSN needed — with no DSN, events go ONLY to the local server (nothing
# reaches the user's Sentry org, no production quota). With a DSN set, the
# SDK sends to both.
sentry local run -- npm run dev          # or: python manage.py runserver, etc.

# Watch only AI/agent (gen_ai, mcp) spans while iterating on an agent.
sentry local -f ai

# Server-side SDKs read SENTRY_SPOTLIGHT automatically. The CLI also injects
# the URL under every framework client prefix (NEXT_PUBLIC_, VITE_, PUBLIC_,
# NUXT_PUBLIC_, REACT_APP_, VUE_APP_, GATSBY_). Until the browser SDK reads
# these automatically (getsentry/sentry-javascript#18198), reference the var
# matching your framework in the client config:
# Sentry.init({ spotlight: process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT ?? false })

浏览 API 架构

# Browse all API resource categories
sentry schema

# Search for endpoints related to a resource
sentry schema issues

# Get details about a specific endpoint
sentry schema "GET /api/0/organizations/{organization_id_or_slug}/issues/"

管理发布版本

# Create a release — version must match Sentry.init({ release }) exactly
sentry release create my-org/1.0.0 --project my-project

# Associate commits via repository integration (needs local git checkout)
sentry release set-commits my-org/1.0.0 --auto

# Or read commits from local git history (no integration needed)
sentry release set-commits my-org/1.0.0 --local

# Mark the release as finalized
sentry release finalize my-org/1.0.0

# Record a production deploy
sentry release deploy my-org/1.0.0 production

关键信息：

• 位置参数的格式为 <org-slug>/<version>。在 sentry release create sentry/1.0.0 中，sentry 是组织，1.0.0 是版本——斜杠用于分隔组织和版本，不属于版本字符串。
• 版本必须与 Sentry.init() 中的 release 值一致。如果 SDK 使用 "1.0.0"，命令就必须使用 org/1.0.0。
• --auto 需要 Sentry 仓库集成（GitHub/GitLab/Bitbucket）以及本地 git 检出。它会将你的 origin 远程仓库与 Sentry 的仓库列表进行匹配。没有本地检出时，请使用 --local。
• 如果没有指定标志，set-commits 会先尝试 --auto，失败后再回退到 --local。

任意 API 访问

# GET request (default)
sentry api /api/0/organizations/my-org/

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

仪表板布局

Sentry 仪表板使用 6 列网格。添加小组件时，尽量填满整行（宽度总和应为 6）。

显示类型的默认尺寸：

显示类型	宽度	高度	类别	备注
big_number	2	1	常用	紧凑的 KPI——每行放置 3 个（2+2+2=6）
line	3	2	常用	半宽图表——每行放置 2 个（3+3=6）
area	3	2	常用	半宽图表——每行放置 2 个
bar	3	2	常用	半宽图表——每行放置 2 个
table	6	2	常用	全宽——始终独占一行
stacked_area	3	2	专用	堆叠面积图
top_n	3	2	专用	排名前 N 的列表
categorical_bar	3	2	专用	分类条形图
text	3	2	专用	静态文本/Markdown 小组件
details	3	2	内部	详情视图
wheel	3	2	内部	饼图/轮图
rage_and_dead_clicks	3	2	内部	愤怒/无效点击可视化
server_tree	3	2	内部	层级树视图
agents_traces_table	3	2	内部	Agent 追踪表

通用仪表板请使用常用类型。只有在明确提出要求时才使用专用类型。除非用户明确要求，否则请避免使用内部类型。

可用数据集：spans（默认）、tracemetrics、discover、issue、error-events、logs。运行 sentry dashboard widget --help 可查看数据集说明、查询格式和示例。

填满整行的示例：

# 3 KPIs filling one row (2+2+2 = 6)
sentry dashboard widget add <dashboard> "Error Count" --display big_number --query count
sentry dashboard widget add <dashboard> "P95 Duration" --display big_number --query p95:span.duration
sentry dashboard widget add <dashboard> "Throughput" --display big_number --query epm

# 2 charts filling one row (3+3 = 6)
sentry dashboard widget add <dashboard> "Errors Over Time" --display line --query count
sentry dashboard widget add <dashboard> "Latency Over Time" --display line --query p95:span.duration

# Full-width table (6 = 6)
sentry dashboard widget add <dashboard> "Top Endpoints" --display table \
  --query count --query p95:span.duration \
  --group-by transaction --sort -count --limit 10

快速参考

时间筛选

使用 --period（别名：-t）按时间范围筛选：

sentry trace list --period 1h
sentry span list --period 24h
sentry span list -t 7d

限定组织或项目范围

按照 gh CLI 的惯例，组织和项目是位置参数：

sentry trace list my-org/my-project
sentry issue list my-org/my-project
sentry span list my-org/my-project/abc123def456...

列出追踪中的跨度

将追踪 ID 作为位置参数传给 span list：

sentry span list abc123def456...
sentry span list my-org/my-project/abc123def456...

Events API 的数据集名称

查询 Events API 时（直接查询或通过 sentry api），有效的数据集值为：spans、transactions、logs、errors、discover。

常见错误

• 错误的问题 ID 格式：请使用 PROJECT-123（短 ID），而不是数字 ID 123456789。短 ID 包含项目前缀。
• 不必要的预先身份验证：不要在每条命令前运行 sentry auth login。CLI 会检测缺失或过期的身份验证，并自动提示。只有在需要切换账户时，才运行 sentry auth login。
• 管道操作时缺少 --json：人类可读的输出包含格式化内容。以编程方式解析输出时，请使用 --json。
• 不需要时指定组织／项目：自动检测会从 .sentryclirc 配置文件、DSN、环境变量和目录名称中解析组织／项目。先让它自动处理；只有在 CLI 提示无法检测目标或检测到错误目标时，才添加 <org>/<project>。
• 混淆 --query 语法：--query 标志使用 Sentry 搜索语法（例如 is:unresolved、assigned:me），而不是自由文本搜索。
• 没有使用 --web：查看命令支持使用 -w／--web 在浏览器中打开资源，便于分享链接。
• 获取 API 架构而不是使用 CLI：请优先使用 sentry schema 浏览 API，并使用 sentry api 发送请求。CLI 会处理身份验证和端点解析，因此通常无需单独下载 OpenAPI 规范。
• 发布版本不匹配：org/version 位置参数的格式为 <org-slug>/<version>，其中 org/ 表示组织，并非版本的一部分。sentry release create sentry/1.0.0 会在组织 sentry 中创建版本 1.0.0。如果你的 Sentry.init() 使用 release: "1.0.0"，这样就是正确的。不要重复添加前缀，例如 sentry/myapp/1.0.0。
• 没有 Git 检出时运行 set-commits --auto：--auto 需要本地 Git 仓库，以发现 origin 远程 URL 和 HEAD 提交。在 CI 中，请确保在运行 set-commits --auto 前执行 actions/checkout，并设置 fetch-depth: 0。
• CLI 命令已足够时仍使用 sentry api：sentry issue list --json 和 sentry issue view --json 已在顶层包含 shortId、title、count、userCount、priority、level、status、permalink 等字段。使用 --fields 选择 count 或 userCount 等特定字段时，CLI 会自动确保这些字段出现在 API 响应中。使用 --fields 选择特定字段，并通过 --help 查看所有可用字段。只有在 CLI 未提供所需数据时，才使用 sentry api。

前置条件

使用前必须安装 CLI 并完成身份验证。

安装

curl https://cli.sentry.dev/install -fsS | bash
curl https://cli.sentry.dev/install -fsS | bash -s -- --version nightly

# Or install via npm/pnpm/bun
npm install -g sentry

身份验证

sentry auth login
sentry auth login --token YOUR_SENTRY_API_TOKEN
sentry auth status
sentry auth logout

命令参考

Auth

使用 Sentry 进行身份验证

• sentry auth login — 使用 Sentry 进行身份验证
• sentry auth logout — 退出 Sentry
• sentry auth refresh — 刷新身份验证令牌
• sentry auth status — 查看身份验证状态
• sentry auth token — 输出已存储的身份验证令牌
• sentry auth whoami — 显示当前通过身份验证的身份

→ 完整标志和示例：references/auth.md

Org

使用 Sentry 组织

• sentry org list — 列出组织
• sentry org view <org> — 查看组织详情

→ 完整标志和示例：references/org.md

Project

使用 Sentry 项目

• sentry project create <name> <platform> — 创建新项目
• sentry project delete <org/project> — 删除项目
• sentry project list <org/project> — 列出项目
• sentry project view <org/project> — 查看项目详情

→ 完整标志和示例：references/project.md

Issue

管理 Sentry 问题

• sentry issue list <org/project> — 列出项目中的问题
• sentry issue events <issue> — 列出特定问题的事件
• sentry issue explain <issue> — 使用 Seer AI 分析问题的根本原因
• sentry issue plan <issue> — 使用 Seer AI 生成解决方案计划
• sentry issue view <issue> — 查看特定问题的详细信息
• sentry issue resolve <issue> — 将问题标记为已解决
• sentry issue unresolve <issue> — 重新打开已解决的问题
• sentry issue archive <issue> — 归档（忽略）问题
• sentry issue merge <issue...> — 将 2 个或更多问题合并为一个规范分组

→ 完整标志和示例：references/issue.md

Event

查看、列出和发送 Sentry 事件

• sentry event view <org/project/event-id...> — 查看一个或多个事件的详细信息
• sentry event list <issue> — 列出问题的事件
• sentry event send <args...> — 发送 Sentry 事件

→ 完整标志和示例：references/event.md

API

发起经过身份验证的 API 请求

• sentry api <endpoint> — 发起经过身份验证的 API 请求

→ 完整标志和示例：references/api.md

Alert

管理 Sentry 警报规则

• sentry alert issues list <org/project> — 列出问题警报规则
• sentry alert issues view <org/project/rule-id-or-name> — 查看问题警报规则
• sentry alert issues create <target> — 创建问题警报规则
• sentry alert issues delete <org/project/rule-id-or-name> — 删除问题警报规则
• sentry alert issues edit <org/project/rule-id-or-name> — 编辑问题警报规则
• sentry alert metrics list <target> — 列出指标警报规则
• sentry alert metrics view <org/rule-id-or-name> — 查看指标警报规则
• sentry alert metrics create <org> — 创建指标警报规则
• sentry alert metrics delete <org/rule-id-or-name> — 删除指标警报规则
• sentry alert metrics edit <org/rule-id-or-name> — 编辑指标警报规则

→ 完整标志和示例：references/alert.md

CLI

与 CLI 相关的命令

• sentry cli defaults <key value...> — 查看和管理默认设置
• sentry cli feedback <message...> — 发送有关 CLI 的反馈
• sentry cli fix — 诊断并修复 CLI 数据库问题
• sentry cli import — 从旧版 .sentryclirc 文件导入设置
• sentry cli setup — 配置 shell 集成
• sentry cli uninstall — 卸载 Sentry CLI
• sentry cli upgrade <version> — 将 Sentry CLI 更新到最新版本

→ 完整标志和示例：references/cli.md

Code-mappings

管理用于堆栈跟踪链接的代码映射

• sentry code-mappings upload <path> — 上传用于堆栈跟踪链接的代码映射

→ 完整标志和示例：references/code-mappings.md

Dart-symbol-map

使用 Dart/Flutter 符号映射

• sentry dart-symbol-map upload <path> — 将 Dart/Flutter 符号映射上传到 Sentry

→ 完整标志和示例：references/dart-symbol-map.md

Dashboard

管理 Sentry 仪表板

• sentry dashboard list <org/title-filter...> — 列出仪表板
• sentry dashboard view <org/project/dashboard...> — 查看仪表板
• sentry dashboard create <org/project/title...> — 创建仪表板
• sentry dashboard widget add <org/project/dashboard/title...> — 向仪表板添加组件
• sentry dashboard widget edit <org/project/dashboard...> — 编辑仪表板中的组件
• sentry dashboard widget delete <org/project/dashboard...> — 从仪表板删除组件
• sentry dashboard revisions <org/dashboard...> — 列出仪表板修订版本
• sentry dashboard restore <org/dashboard...> — 恢复仪表板修订版本

→ 完整标志和示例：references/dashboard.md

Proguard

使用 ProGuard/R8 映射文件

• sentry proguard upload <path...> — 将 ProGuard/R8 映射文件上传到 Sentry
• sentry proguard uuid <path> — 计算 ProGuard 映射文件的 UUID

→ 完整标志和示例：references/proguard.md

Replay

搜索和检查 Session Replays

• sentry replay list <org/project> — 列出最近的 Session Replays
• sentry replay view <replay-id-or-url...> — 查看 Session Replay

→ 完整标志和示例：references/replay.md

Release

使用 Sentry 发布版本

• sentry release list <org/project> — 列出发布版本及其采用情况和健康指标
• sentry release view <org/version> — 查看发布版本详情及健康指标
• sentry release create <org/version> — 创建发布版本
• sentry release finalize <org/version> — 完成发布版本
• sentry release delete <org/version> — 删除发布版本
• sentry release archive <org/version> — 归档发布版本
• sentry release restore <org/version> — 恢复已归档的发布版本
• sentry release deploy <org/version> <environment> <name> — 为发布版本创建部署
• sentry release deploys <org/version> — 列出发布版本的部署
• sentry release set-commits <org/version> — 为发布版本设置提交
• sentry release propose-version — 提议发布版本号

→ 完整标志和示例：references/release.md

Repo

使用 Sentry 仓库

• sentry repo list <org/project> — 列出仓库

→ 完整标志和示例：references/repo.md

Team

使用 Sentry 团队

• sentry team list <org/project> — 列出团队

→ 完整标志和示例：references/team.md

Explore

查询聚合事件数据（Explore）

• sentry explore <target> — 查询聚合事件数据（Explore）

→ 完整标志和示例：references/explore.md

Log

查看 Sentry 日志

• sentry log list <org/project-or-trace-id...> — 列出项目中的日志
• sentry log view <org/project/log-id...> — 查看一个或多个日志条目的详情

→ 完整标志和示例：references/log.md

Monitor

使用 Sentry cron 监控器

• sentry monitor run <monitor-slug command...> — 使用 cron 监控器签到包装命令
• sentry monitor list <org/project> — 列出 cron 监控器

→ 完整标志和示例：references/monitor.md

Sourcemap

管理 sourcemap

• sentry sourcemap inject <directory> — 将调试 ID 注入 JavaScript 文件和 sourcemap
• sentry sourcemap upload <directory> — 将 sourcemap 上传到 Sentry
• sentry sourcemap resolve <directory> — 解析并报告 JavaScript 文件的 sourcemap 关联信息

→ 完整标志和示例：references/sourcemap.md

Span

列出并查看项目或跟踪中的 span

• sentry span list <org/project/trace-id...> — 列出项目或跟踪中的 span
• sentry span view <trace-id/span-id...> — 查看指定 span 的详情

→ 完整标志和示例：references/span.md

Trace

查看分布式跟踪

• sentry trace list <org/project> — 列出项目中最近的跟踪
• sentry trace view <org/project/trace-id...> — 查看指定跟踪的详情
• sentry trace logs <org/project/trace-id...> — 查看与跟踪关联的日志

→ 完整标志和示例：references/trace.md

Trial

管理产品试用

• sentry trial list <org> — 列出产品试用
• sentry trial start <name> <org> — 开始产品试用

→ 完整标志和示例：references/trial.md

Init

在项目中初始化 Sentry（实验性）

• sentry init <target> <directory> — 在项目中初始化 Sentry（实验性）

→ 完整标志和示例：references/init.md

Local

用于本地开发的 Sentry

• sentry local serve — 启动本地开发服务并持续输出事件
• sentry local run <command...> — 在启用本地开发服务的情况下运行命令

→ 完整标志和示例：references/local.md

Schema

浏览 Sentry API 架构

• sentry schema <resource...> — 浏览 Sentry API 架构

→ 完整标志和示例：references/schema.md

全局选项

所有命令均支持以下全局选项：

• --help - 显示命令的帮助信息
• --version - 显示 CLI 版本
• --log-level <level> - 设置日志详细程度（error、warn、log、info、debug、trace）。覆盖 SENTRY_LOG_LEVEL
• --verbose - --log-level debug 的简写

输出格式

JSON 输出

大多数列表和查看命令都支持 --json 标志以输出 JSON，便于与其他工具集成：

sentry org list --json | jq '.[] | .slug'

在浏览器中打开

查看命令支持 -w 或 --web 标志，可在浏览器中打开资源：

sentry issue view PROJ-123 -w