sentry-cli

Sentry CLI の使用ガイド

sentry CLI を使用して、コマンドラインから Sentry を操作する方法を説明します。

エージェント向けガイダンス

Sentry CLI を使用する AI コーディングエージェント向けのベストプラクティスと運用ガイダンスです。

主な原則

• コマンドを実行するだけで構いません — CLI は認証と組織／プロジェクトの検出を自動的に処理します。コマンドを実行する前に認証したり、組織／プロジェクトを調べたりしないでください。認証が必要な場合、CLI が対話形式でプロンプトを表示します。
• 生の API 呼び出しより CLI コマンドを優先してください — 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 は組織／プロジェクトを自動検出します — ほとんどのコマンドは、.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 に直接アクセスできます。HTTP メソッドには --method、リクエストボディには --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 は意味を持つ終了コードを使用します。エージェント向けの主な範囲は次のとおりです。

範囲	意味	エージェントの対応
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	common	コンパクトな KPI — 1 行に 3 つ配置（2+2+2=6）
line	3	2	common	半分の幅のグラフ — 1 行に 2 つ配置（3+3=6）
area	3	2	common	半分の幅のグラフ — 1 行に 2 つ配置
bar	3	2	common	半分の幅のグラフ — 1 行に 2 つ配置
table	6	2	common	全幅 — 常に 1 行を占有
stacked_area	3	2	specialized	積み上げ面グラフ
top_n	3	2	specialized	上位 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	エージェントのトレーステーブル

一般的なダッシュボードには common タイプを使用してください。specialized は明示的に要求された場合のみ使用してください。ユーザーから明示的に求められない限り、internal タイプは避けてください。

利用可能なデータセット：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 の形式が間違っている：数値 ID の 123456789 ではなく、PROJECT-123（短縮 ID）を使用してください。短縮 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 を指定してリソースをブラウザーで開けます。リンクの共有に便利です。
• CLI を使わずに API スキーマを取得する：API の参照には sentry schema、リクエストの送信には 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 の前に fetch-depth: 0 を指定した actions/checkout が実行されるようにしてください。
• 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 — 現在認証されている ID を表示します

→ すべてのフラグと例：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 件以上のイシューを 1 つの正規グループに統合します

→ フラグと使用例の詳細：references/issue.md

Event

Sentry イベントを表示、一覧表示、送信します

• sentry event view <org/project/event-id...> — 1 つ以上のイベントの詳細を表示します
• 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 — シェル統合を設定します
• 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

セッションリプレイを検索、調査します

• sentry replay list <org/project> — 最近のセッションリプレイを一覧表示します
• sentry replay view <replay-id-or-url...> — セッションリプレイを表示します

→ フラグと使用例の詳細：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...> — 1 つ以上のログエントリの詳細を表示します

→ フラグと使用例の詳細：references/log.md

Monitor

Sentry の cron モニターを操作します

• sentry monitor run <monitor-slug command...> — cron モニターのチェックインでコマンドをラップします
• sentry monitor list <org/project> — cron モニターを一覧表示します

→ フラグと使用例の詳細：references/monitor.md

Sourcemap

ソースマップを管理します

• sentry sourcemap inject <directory> — JavaScript ファイルとソースマップにデバッグ ID を挿入します
• sentry sourcemap upload <directory> — ソースマップを Sentry にアップロードします
• sentry sourcemap resolve <directory> — JavaScript ファイルのソースマップの関連付けを解決し、報告します

→ フラグと使用例の詳細：references/sourcemap.md

Span

プロジェクトまたはトレースのスパンを一覧表示し、表示します

• sentry span list <org/project/trace-id...> — プロジェクトまたはトレースのスパンを一覧表示します
• sentry span view <trace-id/span-id...> — 特定のスパンの詳細を表示します

→ フラグと使用例の詳細：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