sentry-helper

name	sentry-helper
description	Complete Sentry operations via sentry-cli and REST API - issues, releases, source maps, traces, events When user mentions Sentry, errors, issues, releases, source maps, error tracking, stack traces

Sentry Helper Agent

Overview

Complete Sentry operations via sentry-cli and REST API. This skill replaces Sentry MCP server functionality, providing CLI/API equivalents for all operations.

Runtime SDK — use @sentry/bun under Bun

If a service's start runs under Bun (bun run src/index.ts), use @sentry/bun, not @sentry/node. @sentry/node's transport hooks Node's http/https modules; under Bun's Node-compat layer those hooks don't fire, so Sentry.init logs success and captureException returns cleanly but nothing is ever POSTed — events are silently dropped (birmel showed 0 events while a @sentry/bun service had ~50k). Same API surface, so it's a one-line dependency + import swap. Symptom: SDK reports initialized, app reports captures, server shows zero events — check the SDK package before chasing DSN/network/permissions.

Setting release + environment (this monorepo)

Always pass release and environment to Sentry.init. Conventions across this monorepo: static sites read VITE_SENTRY_RELEASE / PUBLIC_SENTRY_RELEASE; Bun services read Bun.env.VERSION; desktop/RN use the package version. These used to be stamped by the CI pipeline (2.0.0-$BUILDKITE_BUILD_NUMBER), which was removed 2026-07 — builds/deploys are manual now, so set the release env var yourself when building. The post-deploy check is: confirm new events carry a non-null release.

MCP Tool Equivalents Reference

MCP Tool	CLI/API Equivalent
whoami	sentry-cli info or curl "$API/"
find_organizations	sentry-cli organizations list or curl "$API/organizations/"
find_teams	curl "$API/organizations/{org}/teams/"
find_projects	sentry-cli projects list or curl "$API/organizations/{org}/projects/"
find_releases	sentry-cli releases list or curl "$API/organizations/{org}/releases/"
get_issue_details	curl "$API/issues/{id}/"
get_trace_details	curl "$API/organizations/{org}/events-trace/{trace_id}/"
get_event_attachment	curl "$API/projects/{org}/{project}/events/{event_id}/attachments/"
search_events	curl "$API/organizations/{org}/events/"
search_issues	sentry-cli issues list or curl "$API/projects/{org}/{project}/issues/"
search_issue_events	curl "$API/issues/{id}/events/"
find_dsns	curl "$API/projects/{org}/{project}/keys/"
update_issue	curl -X PUT "$API/issues/{id}/"
create_team	curl -X POST "$API/organizations/{org}/teams/"
create_project	curl -X POST "$API/teams/{org}/{team}/projects/"
update_project	curl -X PUT "$API/projects/{org}/{project}/"
create_dsn	curl -X POST "$API/projects/{org}/{project}/keys/"
search_docs	WebSearch or https://docs.sentry.io
get_doc	WebFetch from docs.sentry.io
analyze_issue_with_seer	Manual analysis + get_issue_details

Configuration

CLI Installation

# macOS
brew install getsentry/tools/sentry-cli

# Linux/Windows
curl -sL https://sentry.io/get-cli/ | sh

# npm
npm install -g @sentry/cli

Authentication

# Set environment variables
export SENTRY_AUTH_TOKEN="your-auth-token"
export SENTRY_ORG="your-org"
export SENTRY_PROJECT="your-project"
export API="https://sentry.io/api/0"

# Auth header
AUTH="Authorization: Bearer $SENTRY_AUTH_TOKEN"

# CLI login (interactive)
sentry-cli login

# Verify authentication
sentry-cli info
curl -H "$AUTH" "$API/"

.sentryclirc File

[defaults]
url=https://sentry.io/
org=my-organization
project=my-project

[auth]
token=your-auth-token

[log]
level=info

---

Organization Operations

Get Current User (whoami)

# Via CLI
sentry-cli info

# Via API
curl -H "$AUTH" "$API/"

# Get user details
curl -H "$AUTH" "$API/users/me/"

List Organizations

# Via CLI
sentry-cli organizations list

# Via API
curl -H "$AUTH" "$API/organizations/"

# JSON output
curl -H "$AUTH" "$API/organizations/" | \
  jq '.[] | {slug, name, status}'

---

Team Operations

List Teams

curl -H "$AUTH" "$API/organizations/$ORG/teams/"

# JSON output
curl -H "$AUTH" "$API/organizations/$ORG/teams/" | \
  jq '.[] | {slug, name, memberCount}'

Create Team

curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$API/organizations/$ORG/teams/" \
  -d '{
    "name": "My Team",
    "slug": "my-team"
  }'

---

Project Operations

List Projects

# Via CLI
sentry-cli projects list

# Via API
curl -H "$AUTH" "$API/organizations/$ORG/projects/"

# JSON output
curl -H "$AUTH" "$API/organizations/$ORG/projects/" | \
  jq '.[] | {slug, name, platform}'

Create Project

# Create project under a team
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$API/teams/$ORG/$TEAM/projects/" \
  -d '{
    "name": "My Project",
    "slug": "my-project",
    "platform": "javascript"
  }'

Update Project

curl -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  "$API/projects/$ORG/$PROJECT/" \
  -d '{
    "name": "Updated Project Name",
    "slug": "updated-slug",
    "platform": "python"
  }'

---

Issue Operations

Search Issues

# Via CLI
sentry-cli issues list
sentry-cli issues list --query "is:unresolved"

# Via API
curl -H "$AUTH" "$API/projects/$ORG/$PROJECT/issues/"

# With query filters
curl -G -H "$AUTH" \
  --data-urlencode "query=is:unresolved level:error" \
  "$API/projects/$ORG/$PROJECT/issues/"

# Search across organization
curl -G -H "$AUTH" \
  --data-urlencode "query=is:unresolved" \
  "$API/organizations/$ORG/issues/"

# JSON output
curl -H "$AUTH" "$API/projects/$ORG/$PROJECT/issues/" | \
  jq '.[] | {id, shortId, title, count, userCount}'

Get Issue Details

# By issue ID
curl -H "$AUTH" "$API/issues/$ISSUE_ID/"

# With full details
curl -H "$AUTH" "$API/issues/$ISSUE_ID/" | \
  jq '{
    id,
    shortId,
    title,
    status,
    level,
    count,
    userCount,
    firstSeen,
    lastSeen,
    platform,
    project: .project.slug
  }'

# Get latest event with stacktrace
curl -H "$AUTH" "$API/issues/$ISSUE_ID/events/latest/" | \
  jq '.entries[] | select(.type == "exception")'

Update Issue

# Resolve issue
curl -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  "$API/issues/$ISSUE_ID/" \
  -d '{"status": "resolved"}'

# Ignore issue
curl -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  "$API/issues/$ISSUE_ID/" \
  -d '{"status": "ignored"}'

# Assign to user
curl -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  "$API/issues/$ISSUE_ID/" \
  -d '{"assignedTo": "user:123456"}'

# Assign to team
curl -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  "$API/issues/$ISSUE_ID/" \
  -d '{"assignedTo": "team:789"}'

Search Issue Events

# Get events for an issue
curl -H "$AUTH" "$API/issues/$ISSUE_ID/events/"

# With pagination
curl -H "$AUTH" "$API/issues/$ISSUE_ID/events/?cursor=0:0:1"

# Get specific event
curl -H "$AUTH" "$API/issues/$ISSUE_ID/events/$EVENT_ID/"

---

Event Operations

Search Events

# Events in organization (Discover)
curl -G -H "$AUTH" \
  --data-urlencode "field=title" \
  --data-urlencode "field=event.type" \
  --data-urlencode "field=project" \
  --data-urlencode "field=timestamp" \
  --data-urlencode "query=level:error" \
  --data-urlencode "statsPeriod=24h" \
  "$API/organizations/$ORG/events/"

# Count events
curl -G -H "$AUTH" \
  --data-urlencode "field=count()" \
  --data-urlencode "query=level:error" \
  --data-urlencode "statsPeriod=24h" \
  "$API/organizations/$ORG/events/"

Get Event Attachments

# List attachments for an event
curl -H "$AUTH" \
  "$API/projects/$ORG/$PROJECT/events/$EVENT_ID/attachments/"

# Download specific attachment
curl -H "$AUTH" \
  "$API/projects/$ORG/$PROJECT/events/$EVENT_ID/attachments/$ATTACHMENT_ID/?download=1"

---

Trace Operations

Get Trace Details

# Get full trace
curl -H "$AUTH" \
  "$API/organizations/$ORG/events-trace/$TRACE_ID/"

# With specific project
curl -H "$AUTH" \
  "$API/organizations/$ORG/events-trace/$TRACE_ID/?project=$PROJECT_ID"

---

Release Operations

List Releases

# Via CLI
sentry-cli releases list

# Via API
curl -H "$AUTH" "$API/organizations/$ORG/releases/"

# Filter by project
curl -H "$AUTH" "$API/projects/$ORG/$PROJECT/releases/"

# Search by version
curl -G -H "$AUTH" \
  --data-urlencode "query=2.0" \
  "$API/organizations/$ORG/releases/"

# JSON output
curl -H "$AUTH" "$API/organizations/$ORG/releases/" | \
  jq '.[] | {version, dateCreated, newGroups, projects: [.projects[].slug]}'

Create Release

# Via CLI
sentry-cli releases new $VERSION

# Via API
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$API/organizations/$ORG/releases/" \
  -d '{
    "version": "1.0.0",
    "projects": ["my-project"]
  }'

Finalize Release

sentry-cli releases finalize $VERSION

Associate Commits

# Automatic (from git)
sentry-cli releases set-commits $VERSION --auto

# Manual
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$API/organizations/$ORG/releases/$VERSION/commits/" \
  -d '{
    "commits": [{
      "id": "abc123",
      "repository": "org/repo",
      "message": "Fix bug",
      "author_name": "John Doe",
      "author_email": "[e-mail]"
    }]
  }'

Deploy Release

# Via CLI
sentry-cli releases deploys $VERSION new -e production

# Via API
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$API/organizations/$ORG/releases/$VERSION/deploys/" \
  -d '{
    "environment": "production",
    "name": "Deploy to production"
  }'

---

Source Map Operations

Upload Source Maps

# Upload source maps
sentry-cli sourcemaps upload \
  --org $ORG \
  --project $PROJECT \
  --release $VERSION \
  ./dist

# With URL prefix
sentry-cli sourcemaps upload \
  --org $ORG \
  --project $PROJECT \
  --release $VERSION \
  --url-prefix "~/static/js" \
  ./dist

# Validate source maps
sentry-cli sourcemaps explain \
  --org $ORG \
  --project $PROJECT \
  $EVENT_ID

List Release Files

sentry-cli releases files $VERSION list

---

DSN Operations

List DSNs (Project Keys)

curl -H "$AUTH" "$API/projects/$ORG/$PROJECT/keys/"

# JSON output
curl -H "$AUTH" "$API/projects/$ORG/$PROJECT/keys/" | \
  jq '.[] | {id, name, dsn: .dsn.public}'

Create DSN

curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$API/projects/$ORG/$PROJECT/keys/" \
  -d '{
    "name": "Production Key"
  }'

---

Common Workflows

Complete Release Workflow

#!/bin/bash
set -e

ORG="my-org"
PROJECT="my-project"
VERSION="$(git describe --tags)"

echo "Creating release $VERSION"

# Create release
sentry-cli releases new -p "$PROJECT" "$VERSION"

# Associate commits
sentry-cli releases set-commits "$VERSION" --auto

# Upload source maps
echo "Uploading source maps..."
sentry-cli sourcemaps upload \
  --org "$ORG" \
  --project "$PROJECT" \
  --release "$VERSION" \
  ./dist

# Finalize
sentry-cli releases finalize "$VERSION"

# Create deployment
sentry-cli releases deploys "$VERSION" new \
  -e production \
  -n "$(git rev-parse HEAD)"

echo "Release $VERSION created successfully"

Error Investigation

#!/bin/bash

# 1. List recent high-priority errors
echo "=== Recent Errors ==="
curl -sG -H "$AUTH" \
  --data-urlencode "query=is:unresolved level:error" \
  "$API/projects/$ORG/$PROJECT/issues/" | \
  jq -r '.[] | "\(.shortId)\t\(.count)\t\(.title)"' | head -10

# 2. Get detailed issue info
echo -e "\n=== Issue Details ==="
ISSUE_ID="${1:-}"
if [ -n "$ISSUE_ID" ]; then
  curl -sH "$AUTH" "$API/issues/$ISSUE_ID/" | \
    jq '{shortId, title, status, level, count, userCount, lastSeen}'

  # 3. Get stack trace
  echo -e "\n=== Stack Trace ==="
  curl -sH "$AUTH" "$API/issues/$ISSUE_ID/events/latest/" | \
    jq '.entries[] | select(.type == "exception") | .data.values[0].stacktrace.frames[-5:]'
fi

Issue Triage Script

#!/bin/bash

# Get high-impact unresolved issues
curl -sH "$AUTH" "$API/projects/$ORG/$PROJECT/issues/?query=is:unresolved" | \
  jq -r '.[] | select(.count > 100) | "\(.shortId)\t\(.title)\t\(.count)"' | \
  sort -t$'\t' -k3 -nr | \
  column -t -s$'\t'

Monitor Error Rate

#!/bin/bash

# Get error count for last 24 hours
curl -sG -H "$AUTH" \
  --data-urlencode "field=count()" \
  --data-urlencode "query=level:error" \
  --data-urlencode "statsPeriod=24h" \
  "$API/organizations/$ORG/events/" | \
  jq '.data[0]."count()"'

---

CI/CD Integration

GitHub Actions Example

- name: Create Sentry release
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    SENTRY_ORG: my-org
    SENTRY_PROJECT: my-project
  run: |
    curl -sL https://sentry.io/get-cli/ | sh

    export VERSION=$(git rev-parse --short HEAD)
    sentry-cli releases new "$VERSION"
    sentry-cli releases set-commits "$VERSION" --auto
    sentry-cli sourcemaps upload --release="$VERSION" ./build
    sentry-cli releases finalize "$VERSION"
    sentry-cli releases deploys "$VERSION" new -e production

---

SDK Integration

JavaScript/TypeScript

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "your-dsn",
  release: process.env.SENTRY_RELEASE,
  environment: process.env.NODE_ENV,
  integrations: [new Sentry.BrowserTracing()],
  tracesSampleRate: 1.0,
});

Python

import sentry_sdk

sentry_sdk.init(
    dsn="your-dsn",
    release=os.getenv("SENTRY_RELEASE"),
    environment=os.getenv("ENVIRONMENT"),
    traces_sample_rate=1.0,
)

---

Troubleshooting

Source Maps Not Working

# Verify source maps uploaded
sentry-cli releases files $VERSION list

# Explain why source map isn't working
sentry-cli sourcemaps explain \
  --org $ORG \
  --project $PROJECT \
  $EVENT_ID

Authentication Issues

# Verify token works
sentry-cli info

# Test API access
curl -H "$AUTH" "$API/"

---

Query Syntax

Common issue search queries:

# Unresolved errors
is:unresolved level:error

# High frequency issues
is:unresolved count:>100

# Issues affecting many users
is:unresolved users:>10

# Recent issues
is:unresolved firstSeen:-24h

# Specific browser
browser.name:Chrome

# Specific release
release:1.0.0

# Assigned to me
assigned:me

# Not assigned
!is:assigned

# Has specific tag
myTag:value

---

When to Ask for Help

Ask the user for clarification when:

• Organization or project slug is not specified
• Sentry URL format is ambiguous (self-hosted vs SaaS)
• Release version strategy isn't clear
• Source map paths or build output locations are unknown
• Issue assignment or resolution workflow needs clarification
• DSN vs API token usage is unclear