Sentry CLI 使用指南：命令行工具与Sentry交互、问题调试和API探索

sentry-cli by getsentry/cli

111 周安装量

53 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/getsentry/cli --skill sentry-cli

命令行工具监控调试

🇨🇳中文介绍

Sentry CLI 使用指南

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

AI 助手指导原则

为使用 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 规范更快。
使用调查问题 — 当被问及特定问题（例如、）时，请直接使用。

广告位招租

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

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

联系我们

相关 Skills

前端性能优化指南：识别瓶颈与优化策略，提升LCP、FID、CLS核心指标

47,000 周安装

前端代码审计工具 - 自动化检测可访问性、性能、响应式设计、主题化与反模式

46,200 周安装

浏览器自动化策略指南：何时及如何使用实时浏览器会话进行网页调试与研究

43,400 周安装

网站审计工具 - 使用 squirrelscan CLI 全面检测 SEO、性能、安全及技术问题

43,300 周安装

gh (GitHub CLI) 惯例：sentry CLI 使用相同的 <名词> <动词> 命令模式（例如 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，那么相同的模式也适用。

在列表命令上使用 --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> 参数，而不是依赖自动检测

显示类型	宽度	高度	类别	备注
`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	2	common	半宽图表 — 每行放置 2 个
`table`	6	2	common	全宽 — 始终独占一行
`stacked_area`	3	2	specialized	堆叠面积图
`top_n`	3	2	specialized	Top N 排名列表
`categorical_bar`	3	2	specialized	分类条形图
`text`	3	2	specialized	静态文本/markdown 小部件
`details`	3	2	internal	详情视图
`wheel`	3	2	internal	饼图/轮形图
`rage_and_dead_clicks`	3	2	internal	狂怒点击/死点击可视化
`server_tree`	3	2	internal	分层树状显示
`agents_traces_table`	3	2	internal	代理追踪表

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

# 3 个 KPI 填满一行 (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 个图表填满一行 (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

# 全宽表格 (6 = 6)
sentry dashboard widget add <dashboard> "Top Endpoints" --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 语法：--query 标志使用 Sentry 搜索语法（例如 is:unresolved、assigned:me），而不是自由文本搜索。
未使用 --web：查看命令支持 -w/--web 以在浏览器中打开资源 — 便于分享链接。
获取 API 架构而非使用 CLI：优先使用 sentry schema 浏览 API 和使用 sentry api 发出请求 — CLI 会处理身份验证和端点解析，因此很少需要单独下载 OpenAPI 规范。

sentry auth login — 与 Sentry 进行身份验证
sentry auth logout — 从 Sentry 注销
sentry auth refresh — 刷新您的身份验证令牌
sentry auth status — 查看身份验证状态
sentry auth token — 打印存储的身份验证令牌
sentry auth whoami — 显示当前已验证的用户

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

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

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

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...> — 从仪表板中删除小部件

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

🇺🇸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.
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.

Design Principles

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/ for filtering, / for result count.

Context Window Tips

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

Safety Rules

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

Workflow Patterns

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

# 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"}'

Dashboard Layout

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`

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

Common Mistakes

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 syntax: The flag uses Sentry search syntax (e.g., , ), not free text search.

Prerequisites

The CLI must be installed and authenticated before use.

Installation

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

Authentication

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

Command Reference

Auth

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

Org

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

Project

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

Issue

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

Event

View Sentry events

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

→ Full flags and examples: references/events.md

Api

Make an authenticated API request

sentry api <endpoint> — Make an authenticated API request

→ Full flags and examples: references/api.md

Cli

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

Dashboard

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

Repo

Work with Sentry repositories

sentry repo list <org/project> — List repositories

→ Full flags and examples: references/teams.md

Team

Work with Sentry teams

sentry team list <org/project> — List teams

→ Full flags and examples: references/teams.md

Log

View Sentry logs

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

Sourcemap

Manage sourcemaps

sentry sourcemap inject <directory> — Inject debug IDs into JavaScript files and sourcemaps
sentry sourcemap upload <directory> — Upload sourcemaps to Sentry

→ Full flags and examples: references/sourcemap.md

Span

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

Trace

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

Trial

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

Init

Initialize Sentry in your project (experimental)

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

→ Full flags and examples: references/setup.md

Schema

Browse the Sentry API schema

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

→ Full flags and examples: references/setup.md

Global Options

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

Output Formats

JSON Output

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'

Opening in Browser

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

sentry issue view PROJ-123 -w

Weekly Installs

Repository

getsentry/cli

GitHub Stars

First Seen

Jan 29, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode79

github-copilot78

codex77

claude-code75

gemini-cli74

cursor73

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.

Sentry CLI 使用指南：命令行工具与Sentry交互、问题调试和API探索

🇨🇳中文介绍

Sentry CLI 使用指南

AI 助手指导原则

核心原则

相关 Skills

设计原则

上下文窗口提示

安全规则

工作流模式

调查问题

探索追踪和性能

流式传输日志

探索 API 架构

任意 API 访问

仪表板布局

常见错误

先决条件

安装

身份验证

命令参考

Auth

Org

Project

Issue

Event

Api

Cli

Dashboard

Repo

Team

Log

Sourcemap

Span

Trace

Trial

Init

Schema

全局选项

输出格式

JSON 输出

在浏览器中打开

🇺🇸English

Sentry CLI Usage Guide

Agent Guidance

Key Principles

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

Sourcemap

Span

Trace

Trial

Init

Schema

Global Options

Output Formats