Sentry CLI 使用指南：命令行工具与Sentry监控平台交互的最佳实践

sentry-cli by sentry/dev

5,400 周安装量

安装命令

npx skills add https://cli.sentry.dev

开发开发运维监控

🇨🇳中文介绍

Sentry CLI 使用指南

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

智能体指导原则

为使用 Sentry CLI 的 AI 编码智能体提供最佳实践和操作指导。

核心原则

优先使用 CLI 命令而非原始 API 调用 — CLI 为大多数任务提供了专用命令。在手动构建 API 调用或获取外部文档之前，请优先使用 sentry issue view、sentry issue list、sentry trace view 等命令。
使用 sentry schema 探索 API — 如果需要发现 API 端点，可以运行 sentry schema 进行交互式浏览，或运行 sentry schema <resource> 进行搜索。这比从外部获取 OpenAPI 规范更快。
使用 sentry issue view <id> 调查问题 — 当被问及特定问题（例如 CLI-G5、PROJECT-123）时，直接使用 sentry issue view。
使用 --json 获取机器可读输出 — 可通过 jq 进行管道过滤。人类可读的输出包含难以解析的格式。
CLI 自动检测组织/项目 — 通过扫描 .env 文件和源代码中的 DSN，大多数命令无需显式指定目标即可工作。

设计原则

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

gh (GitHub CLI) 惯例：sentry CLI 使用相同的 <名词> <动词> 命令模式（例如 sentry issue list、sentry org view）。标志遵循 gh 惯例：--json 用于机器可读输出，--fields 用于选择特定字段，-w/--web 用于在浏览器中打开，-q/--query 用于过滤，/ 用于限制结果数量。

上下文窗口使用技巧

在列表命令上使用 --fields id,title,status 以减少输出大小
在命令之间管道传输输出或以编程方式处理时，使用 --json
使用 --limit 来限制结果数量（默认值通常为 10–100）
优先使用 sentry issue view PROJECT-123，而不是手动列出和过滤
对于专用命令未覆盖的端点，使用 sentry api

安全规则

在运行破坏性命令之前始终与用户确认：project delete、trial start
在执行变更操作之前，验证组织/项目上下文是否正确 — 使用 sentry auth status 检查默认值
切勿存储或记录身份验证令牌 — 使用 sentry auth login 并让 CLI 管理凭据
如果对目标组织/项目有疑问，请使用显式的 <org>/<project> 参数，而不是依赖自动检测

工作流模式

调查问题

# 1. 查找问题
sentry issue list my-org/my-project --query "is:unresolved" --limit 5

# 2. 获取详细信息
sentry issue view PROJECT-123

# 3. 获取 AI 根因分析
sentry issue explain PROJECT-123

# 4. 获取修复计划
sentry issue plan PROJECT-123

探索追踪和性能

# 1. 列出最近的追踪
sentry trace list my-org/my-project --limit 5

# 2. 查看带有跨度树的特定追踪
sentry trace view my-org/my-project/abc123def456...

# 3. 查看追踪的跨度
sentry span list my-org/my-project/abc123def456...

# 4. 查看与追踪关联的日志
sentry trace logs my-org/abc123def456...

流式日志

# 实时流式传输日志
sentry log list my-org/my-project --follow

# 按严重性过滤日志
sentry log list my-org/my-project --query "severity:error"

探索 API 模式

# 浏览所有 API 资源类别
sentry schema

# 搜索与资源相关的端点
sentry schema issues

# 获取特定端点的详细信息
sentry schema "GET /api/0/organizations/{organization_id_or_slug}/issues/"

任意 API 访问

# GET 请求（默认）
sentry api /api/0/organizations/my-org/

# 带有数据的 POST 请求
sentry api /api/0/organizations/my-org/projects/ --method POST --data '{"name":"new-project","platform":"python"}'

仪表板布局

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

显示类型及其默认尺寸：

显示类型	宽度	高度	类别	备注
`big_number`	2	1	common	紧凑型 KPI — 每行放置 3 个 (2+2+2=6)
`line`	3	2	common	半宽图表 — 每行放置 2 个 (3+3=6)
`area`	3	2	common	半宽图表 — 每行放置 2 个
`bar`	3

对于通用仪表板，请使用 common 类型。仅在明确要求时使用 specialized 类型。除非用户明确要求，否则避免使用 internal 类型。

可用数据集：spans（默认，涵盖大多数用例）、discover、issue、error-events、transaction-like、metrics、logs、tracemetrics、preprod-app-size。

运行 sentry dashboard widget --help 可查看包含聚合函数的完整列表。

填满整行的示例：

# 3 个 KPI 填满一行 (2+2+2 = 6)
sentry dashboard widget add <dashboard> "错误计数" --display big_number --query count
sentry dashboard widget add <dashboard> "P95 持续时间" --display big_number --query p95:span.duration
sentry dashboard widget add <dashboard> "吞吐量" --display big_number --query epm

# 2 个图表填满一行 (3+3 = 6)
sentry dashboard widget add <dashboard> "随时间变化的错误数" --display line --query count
sentry dashboard widget add <dashboard> "随时间变化的延迟" --display line --query p95:span.duration

# 全宽表格 (6 = 6)
sentry dashboard widget add <dashboard> "热门端点" --display table \
  --query count --query p95:span.duration \
  --group-by transaction --sort -count --limit 10

常见错误

错误的问题 ID 格式：使用 PROJECT-123（短 ID），而不是数字 ID 123456789。短 ID 包含项目前缀。
忘记身份验证：在任何其他命令之前运行 sentry auth login。使用 sentry auth status 进行检查。
管道传输时缺少 --json：人类可读的输出包含格式。以编程方式解析输出时，请使用 --json。
组织/项目不明确：自动检测会扫描 .env 文件和源代码中的 DSN。如果项目不明确，请明确指定：sentry issue list my-org/my-project。
混淆 --query 语法：标志使用 Sentry 搜索语法（例如、），而不是自由文本搜索。

先决条件

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

安装

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

# 或通过 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/organizations.md

Project

处理 Sentry 项目

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

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

Issue

管理 Sentry 问题

sentry issue list <org/project> — 列出项目中的问题
sentry issue explain <issue> — 使用 Seer AI 分析问题的根本原因
sentry issue plan <issue> — 使用 Seer AI 生成解决方案计划
sentry issue view <issue> — 查看特定问题的详细信息

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

Event

查看 Sentry 事件

sentry event view <args...> — 查看特定事件的详细信息

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

Api

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

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

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

Cli

CLI 相关命令

sentry cli feedback <message...> — 发送关于 CLI 的反馈
sentry cli fix — 诊断并修复 CLI 数据库问题
sentry cli setup — 配置 shell 集成
sentry cli upgrade <version> — 将 Sentry CLI 更新到最新版本

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

Dashboard

管理 Sentry 仪表板

sentry dashboard list <org/project> — 列出仪表板
sentry dashboard view <args...> — 查看仪表板
sentry dashboard create <args...> — 创建仪表板
sentry dashboard widget add <args...> — 向仪表板添加小部件
sentry dashboard widget edit <args...> — 编辑仪表板中的小部件
sentry dashboard widget delete <args...> — 从仪表板中删除小部件

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

Repo

处理 Sentry 仓库

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

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

Team

处理 Sentry 团队

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

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

Log

查看 Sentry 日志

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

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

Span

列出和查看项目或追踪中的跨度

sentry span list <org/project/trace-id...> — 列出项目或追踪中的跨度
sentry span view <trace-id/span-id...> — 查看特定跨度的详细信息

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

Trace

查看分布式追踪

sentry trace list <org/project> — 列出项目中的最近追踪
sentry trace view <org/project/trace-id...> — 查看特定追踪的详细信息
sentry trace logs <org/trace-id...> — 查看与追踪关联的日志

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

Trial

管理产品试用

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

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

Init

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

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

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

Schema

浏览 Sentry API 模式

sentry schema <resource...> — 浏览 Sentry API 模式

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

全局选项

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

--help - 显示命令的帮助信息
--version - 显示 CLI 版本
--log-level <level> - 设置日志详细级别 (error、warn、log、info、debug、trace)。覆盖 SENTRY_LOG_LEVEL
--verbose - 的简写形式

输出格式

JSON 输出

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

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

在浏览器中打开

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

sentry issue view PROJ-123 -w

每周安装量

4.7K

来源

cli.sentry.dev

首次出现

2026年2月28日

安全审计

Gen Agent Trust HubFail SocketPass SnykFail

安装于

claude-code1.6K

codex936

gemini-cli919

opencode697

kimi-cli595

cursor142

🇺🇸English

Sentry CLI Usage Guide

Help users interact with Sentry from the command line using the sentry CLI.

Agent Guidance

Best practices and operational guidance for AI coding agents using the Sentry CLI.

Key Principles

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.
Usesentry 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.

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

733,500 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

252,100 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

202,600 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

133,200 周安装

sentry api 模仿 curl：sentry api 命令通过类似 curl 的接口提供直接的 API 访问 — --method 用于 HTTP 方法，--data 用于请求体，--header 用于自定义头部。它会自动处理身份验证。如果您知道如何使用 curl 调用 REST API，同样的模式也适用。

不使用 --web：查看命令支持 -w/--web 标志以在浏览器中打开资源 — 对于分享链接很有用。

获取 API 模式而不是使用 CLI：优先使用 sentry schema 浏览 API 和使用 sentry api 发出请求 — CLI 会处理身份验证和端点解析，因此很少需要单独下载 OpenAPI 规范。

Usesentry issue view <id> to investigate issues — when asked about a specific issue (e.g., CLI-G5, PROJECT-123), use sentry issue view directly.

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 — most commands work without explicit targets by scanning for DSNs in .env files and source code.

The sentry CLI follows conventions from well-known tools — if you're familiar with them, that knowledge transfers directly:

gh (GitHub CLI) conventions: The sentry CLI uses the same <noun> <verb> command pattern (e.g., sentry issue list, sentry org view). Flags follow gh conventions: --json for machine-readable output, --fields to select specific fields, -w/--web to open in browser, -q/--query for filtering, -n/--limit for result count.
sentry api mimics curl: The sentry api command provides direct API access with a curl-like interface — --method for HTTP method, --data for request body, --header for custom headers. It handles authentication automatically. If you know how to call a REST API with curl, the same patterns apply.

Use --fields id,title,status on list commands to reduce output size
Use --json when piping output between commands or processing programmatically
Use --limit to cap the number of results (default is usually 10–100)
Prefer sentry issue view PROJECT-123 over listing and filtering manually
Use sentry api for endpoints not covered by dedicated commands

Always confirm with the user before running destructive commands: project delete, trial start
Verify the org/project context is correct before mutations — use sentry auth status to check defaults
Never store or log authentication tokens — use sentry auth login and let the CLI manage credentials
When in doubt about the target org/project, use explicit <org>/<project> arguments instead of auto-detection

Investigate an Issue

# 1. Find the issue
sentry issue list my-org/my-project --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

Explore Traces and Performance

# 1. List recent traces
sentry trace list my-org/my-project --limit 5

# 2. View a specific trace with span tree
sentry trace view my-org/my-project/abc123def456...

# 3. View spans for a trace
sentry span list my-org/my-project/abc123def456...

# 4. View logs associated with a trace
sentry trace logs my-org/abc123def456...

# Stream logs in real-time
sentry log list my-org/my-project --follow

# Filter logs by severity
sentry log list my-org/my-project --query "severity:error"

Explore the API Schema

# 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/"

Arbitrary API Access

# 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 dashboards use a 6-column grid. When adding widgets, aim to fill complete rows (widths should sum to 6).

Display types with default sizes:

Display Type	Width	Height	Category	Notes
`big_number`	2	1	common	Compact KPI — place 3 per row (2+2+2=6)
`line`	3	2	common	Half-width chart — place 2 per row (3+3=6)
`area`	3	2	common	Half-width chart — place 2 per row
`bar`	3	2	common	Half-width chart — place 2 per row
`table`	6	2	common	Full-width — always takes its own row
`stacked_area`	3	2	specialized	Stacked area chart
`top_n`	3	2	specialized	Top N ranked list
`categorical_bar`	3	2	specialized	Categorical bar chart
`text`	3	2	specialized	Static text/markdown widget
`details`	3	2	internal	Detail view
`wheel`	3	2	internal	Pie/wheel chart
`rage_and_dead_clicks`	3	2	internal	Rage/dead click visualization
`server_tree`	3	2	internal	Hierarchical tree display
`agents_traces_table`	3	2	internal	Agents traces table

Use common types for general dashboards. Use specialized only when specifically requested. Avoid internal types unless the user explicitly asks.

Available datasets: spans (default, covers most use cases), discover, issue, error-events, transaction-like, metrics, logs, tracemetrics, preprod-app-size.

Run sentry dashboard widget --help for the full list including aggregate functions.

Row-filling examples:

# 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

Wrong issue ID format : Use PROJECT-123 (short ID), not the numeric ID 123456789. The short ID includes the project prefix.
Forgetting authentication : Run sentry auth login before any other command. Check with sentry auth status.
Missing--json for piping: Human-readable output includes formatting. Use --json when parsing output programmatically.
Org/project ambiguity : Auto-detection scans for DSNs in .env files and source code. If the project is ambiguous, specify explicitly: sentry issue list my-org/my-project.
Confusing--query syntax: The --query flag uses Sentry search syntax (e.g., is:unresolved, assigned:me), not free text search.
Not using--web: View commands support -w/--web to open the resource in the browser — useful for sharing links.
Fetching API schemas instead of using the CLI : Prefer sentry schema to browse the API and sentry api to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately.

The CLI must be installed and authenticated before use.

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

Authenticate with Sentry

sentry auth login — Authenticate with Sentry
sentry auth logout — Log out of Sentry
sentry auth refresh — Refresh your authentication token
sentry auth status — View authentication status
sentry auth token — Print the stored authentication token
sentry auth whoami — Show the currently authenticated user

→ Full flags and examples: references/auth.md

Work with Sentry organizations

sentry org list — List organizations
sentry org view <org> — View details of an organization

→ Full flags and examples: references/organizations.md

Work with Sentry projects

sentry project create <name> <platform> — Create a new project
sentry project delete <org/project> — Delete a project
sentry project list <org/project> — List projects
sentry project view <org/project> — View details of a project

→ Full flags and examples: references/projects.md

Manage Sentry issues

sentry issue list <org/project> — List issues in a project
sentry issue explain <issue> — Analyze an issue's root cause using Seer AI
sentry issue plan <issue> — Generate a solution plan using Seer AI
sentry issue view <issue> — View details of a specific issue

→ Full flags and examples: references/issues.md

sentry event view <args...> — View details of a specific event

→ Full flags and examples: references/events.md

Make an authenticated API request

sentry api <endpoint> — Make an authenticated API request

→ Full flags and examples: references/api.md

CLI-related commands

sentry cli feedback <message...> — Send feedback about the CLI
sentry cli fix — Diagnose and repair CLI database issues
sentry cli setup — Configure shell integration
sentry cli upgrade <version> — Update the Sentry CLI to the latest version

→ Full flags and examples: references/setup.md

Manage Sentry dashboards

sentry dashboard list <org/project> — List dashboards
sentry dashboard view <args...> — View a dashboard
sentry dashboard create <args...> — Create a dashboard
sentry dashboard widget add <args...> — Add a widget to a dashboard
sentry dashboard widget edit <args...> — Edit a widget in a dashboard
sentry dashboard widget delete <args...> — Delete a widget from a dashboard

→ Full flags and examples: references/dashboards.md

Work with Sentry repositories

sentry repo list <org/project> — List repositories

→ Full flags and examples: references/teams.md

Work with Sentry teams

sentry team list <org/project> — List teams

→ Full flags and examples: references/teams.md

sentry log list <org/project-or-trace-id...> — List logs from a project
sentry log view <args...> — View details of one or more log entries

→ Full flags and examples: references/logs.md

List and view spans in projects or traces

sentry span list <org/project/trace-id...> — List spans in a project or trace
sentry span view <trace-id/span-id...> — View details of specific spans

→ Full flags and examples: references/traces.md

View distributed traces

sentry trace list <org/project> — List recent traces in a project
sentry trace view <org/project/trace-id...> — View details of a specific trace
sentry trace logs <org/trace-id...> — View logs associated with a trace

→ Full flags and examples: references/traces.md

Manage product trials

sentry trial list <org> — List product trials
sentry trial start <name> <org> — Start a product trial

→ Full flags and examples: references/trials.md

Initialize Sentry in your project (experimental)

sentry init <target> <directory> — Initialize Sentry in your project (experimental)

→ Full flags and examples: references/setup.md

Browse the Sentry API schema

sentry schema <resource...> — Browse the Sentry API schema

→ Full flags and examples: references/setup.md

All commands support the following global options:

--help - Show help for the command
--version - Show CLI version
--log-level <level> - Set log verbosity (error, warn, log, info, debug, trace). Overrides SENTRY_LOG_LEVEL
--verbose - Shorthand for --log-level debug

Most list and view commands support --json flag for JSON output, making it easy to integrate with other tools:

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

View commands support -w or --web flag to open the resource in your browser:

sentry issue view PROJ-123 -w

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

Sentry CLI 使用指南：命令行工具与Sentry监控平台交互的最佳实践

🇨🇳中文介绍

Sentry CLI 使用指南

智能体指导原则

核心原则

设计原则

上下文窗口使用技巧

安全规则

工作流模式

调查问题

探索追踪和性能

流式日志

探索 API 模式

任意 API 访问

仪表板布局

常见错误

先决条件

安装

身份验证

命令参考

Auth

Org

Project

Issue

Event

Api

Cli

Dashboard

Repo

Team

Log

Span

Trace

Trial

Init

Schema

全局选项

输出格式

JSON 输出

在浏览器中打开

🇺🇸English

Sentry CLI Usage Guide

Agent Guidance

Key Principles

相关 Skills

Design Principles

Context Window Tips

Safety Rules

Workflow Patterns

Investigate an Issue

Explore Traces and Performance

Stream Logs

Explore the API Schema

Arbitrary API Access

Dashboard Layout

Common Mistakes

Prerequisites

Installation

Authentication

Command Reference

Auth

Org

Project

Issue

Event

Api

Cli

Dashboard

Repo

Team

Log

Span

Trace

Trial

Init

Schema

Global Options

Output Formats

JSON Output

Opening in Browser