Quick Start Guide

This guide will walk you through authenticating with Sentry and running your first commands. In just a few minutes, you’ll be able to list issues, view event details, and get AI-powered debugging insights.

Prerequisites

Sentry CLI installed (see Installation)
A Sentry account (sign up for free)
An existing project in Sentry (optional, but recommended)

Step 1: Authentication

Before using Sentry CLI, you need to authenticate with your Sentry account. Sentry CLI supports two authentication methods:

OAuth Device Flow (Recommended)

The OAuth device flow is the easiest way to authenticate interactively:

sentry auth login

Start the Authentication Flow

Run the command above. You’ll see output like:

Press Enter to open https://sentry.io/device in your browser...

Or visit: https://sentry.io/device
Enter code: ABCD-EFGH

⣾ Waiting for authentication...

Authorize in Your Browser

Press Enter to open the URL automatically, or manually visit https://sentry.io/device in your browser. Enter the code shown in your terminal.

Complete Authorization

Follow the prompts in your browser to authorize the CLI. Once complete, you’ll see:

✓ Authenticated successfully
  Logged in as: [email protected] (username)
  Config saved to: ~/.sentry/config.db

The OAuth flow uses a device code, so you don’t need to copy tokens or expose credentials in your terminal.

API Token Authentication

For CI/CD environments or non-interactive use, authenticate with an API token:

sentry auth login --token YOUR_API_TOKEN

You can create an API token in your Sentry account settings:

Go to Settings → Account → API → Auth Tokens
Click Create New Token
Select the required scopes (at minimum: org:read, project:read, event:read)
Copy the token and use it with the command above

API tokens are stored securely in ~/.sentry/config.db with file permissions set to 600 (owner read/write only).

Environment Variable Authentication

For temporary authentication or CI/CD pipelines, use environment variables:

export SENTRY_AUTH_TOKEN=your_api_token
sentry issue list

Sentry CLI checks for authentication in this order:

SENTRY_AUTH_TOKEN environment variable
SENTRY_TOKEN environment variable
OAuth token stored in ~/.sentry/config.db

Self-Hosted Sentry

If you’re using a self-hosted Sentry instance (version 26.1.0+), you’ll need to configure the OAuth client:

export SENTRY_URL=https://sentry.your-company.com
export SENTRY_CLIENT_ID=your_oauth_client_id
sentry auth login

You must create a public OAuth application in Settings → Developer Settings on your self-hosted instance. For older Sentry versions, use sentry auth login --token instead.

Step 2: Verify Authentication

Check that you’re authenticated successfully:

sentry auth status

You should see output like:

✓ Authenticated
  User: [email protected] (username)
  Organizations: 3
  Token expires: 2026-04-05 14:23:45 UTC

Step 3: Explore Your Organizations and Projects

List your organizations:

sentry org list

Example output:

Slug         Name              Projects
my-company   My Company        12
personal     Personal Projects 3

List projects in an organization:

sentry project list my-company

Example output:

Slug           Name              Platform    Issues
frontend       Frontend App      javascript  45
backend-api    Backend API       python      23
mobile-app     Mobile App        react-native 12

You can also let Sentry CLI auto-detect your project from your codebase (see Step 4).

Step 4: Auto-Detect Your Project

One of Sentry CLI’s most powerful features is automatic project detection. Navigate to a project directory that contains Sentry configuration:

cd ~/my-project
sentry issue list

Sentry CLI will:

Search for Sentry DSN in .env files
Scan source code files (JavaScript, Python, Go, Java, Ruby, PHP) for Sentry initialization
Walk up the directory tree to find project boundaries
Cache the detected project for fast subsequent access

If your project can’t be auto-detected, you can explicitly specify it: sentry issue list my-company/my-project

Step 5: List Issues

View recent issues in your project:

sentry issue list

Example output:

ID          Status      Title                                    Events   First Seen
PROJ-ABC    unresolved  TypeError: Cannot read property 'user'   1.2k     2 days ago
PROJ-DEF    unresolved  ReferenceError: undefined variable       856      3 days ago
PROJ-GHI    resolved    Network request timeout                  342      1 week ago

Filter and Sort Issues

# Only unresolved issues
sentry issue list --status unresolved

# Limit to 10 results
sentry issue list --limit 10

# Issues from the last 24 hours
sentry issue list --period 24h

# Sort by frequency
sentry issue list --sort freq

Step 6: Get AI-Powered Insights

Use Seer AI to get root cause analysis and fix recommendations:

# Get explanation of an issue
sentry issue explain PROJ-ABC

# Generate a fix plan
sentry issue plan PROJ-ABC

Example output for explain:

🤖 Seer AI Analysis

Root Cause:
The error occurs when accessing the 'user' property of an object that is 
undefined. This typically happens when:

1. User session data hasn't loaded yet
2. Authentication state is not properly initialized
3. The user object is null due to logout or session expiration

Key Observations:
- Error happens during component render (line 47 in UserProfile.tsx)
- Affects 15% of users, primarily on mobile devices
- Spike in occurrences started 2 days ago after deployment

Recommended Actions:
1. Add null check before accessing user.email
2. Implement loading state while user data is fetching
3. Consider adding error boundary to gracefully handle auth failures

Seer AI features require Sentry Business or Enterprise plan with AI enabled for your organization.

Step 7: View Issue Details

Get detailed information about a specific issue:

sentry issue view PROJ-ABC

Example output:

Title: TypeError: Cannot read property 'user'
Status: unresolved
Level: error
Platform: javascript
First Seen: 2 days ago
Last Seen: 5 minutes ago

Count: 1,234 events
Users Affected: 156

Stacktrace:
  at UserProfile.render (UserProfile.tsx:47:23)
  at renderComponent (react-dom.js:1234:45)
  at updateComponent (react-dom.js:2345:12)

Tags:
  browser: Chrome 120
  environment: production
  release: v1.2.3

URL: https://sentry.io/organizations/my-company/issues/12345/

Open in Browser

Use the -w flag to open any resource in your browser:

sentry issue view PROJ-ABC -w

Step 8: View Event Details

View a specific event within an issue:

sentry event view EVENT_ID

Events contain detailed information including:

Full stacktrace
Breadcrumbs (user actions leading to the error)
Context (device info, browser, OS)
Tags and custom metadata

Step 9: Export to JSON

All commands support JSON output for scripting and automation:

# Export issues to JSON
sentry issue list --json > issues.json

# Export project list
sentry project list --json | jq '.[] | select(.platform == "python")'

# Pipe to other tools
sentry issue list --json | jq -r '.[] | select(.status == "unresolved") | .id'

JSON output is perfect for integrating Sentry CLI with other tools, CI/CD pipelines, or custom scripts.

Step 10: Make Direct API Requests

For advanced use cases, use the api command to make direct requests to the Sentry API:

# GET request
sentry api /organizations/my-company/projects/

# POST request with data
sentry api POST /organizations/my-company/issues/ISSUE_ID/notes/ \
  --data '{"text": "Investigating this issue"}'

# Include headers
sentry api /api/0/projects/my-company/my-project/events/ \
  --header "X-Custom-Header: value"

Common Workflows

Daily Issue Triage

# Check new unresolved issues from the last 24 hours
sentry issue list --status unresolved --period 24h --sort date

# Explain the top issue
sentry issue explain PROJ-ABC

# Open in browser for more details
sentry issue view PROJ-ABC -w

CI/CD Integration

#!/bin/bash
# Check for new issues after deployment

export SENTRY_AUTH_TOKEN=$CI_SENTRY_TOKEN

ISSUES=$(sentry issue list --period 1h --status unresolved --json)
COUNT=$(echo "$ISSUES" | jq length)

if [ "$COUNT" -gt 10 ]; then
  echo "⚠️  Warning: $COUNT new issues detected after deployment"
  echo "$ISSUES" | jq -r '.[] | "\(.id): \(.title)"'
  exit 1
fi

Monorepo Projects

For monorepos with multiple Sentry projects:

# CLI auto-detects based on your current directory
cd apps/frontend
sentry issue list  # Lists frontend issues

cd ../backend
sentry issue list  # Lists backend issues

# Or explicitly specify the project
sentry issue list my-company/frontend
sentry issue list my-company/backend

Sentry CLI generates short aliases for projects in monorepos, making it easier to switch between them.

Getting Help

Get help for any command:

# General help
sentry --help

# Command-specific help
sentry issue --help
sentry issue list --help

# View all available commands
sentry help

Configuration Files

Sentry CLI stores configuration and cached data in ~/.sentry/:

config.db: SQLite database containing:
- Authentication tokens (OAuth or API tokens)
- Cached project information
- Organization and region mappings
- Project aliases for monorepos
- User information

You can override the config directory:

export SENTRY_CONFIG_DIR=/custom/path
sentry auth login

Logging and Debugging

Enable debug logging to troubleshoot issues:

# Set log level
export SENTRY_LOG_LEVEL=debug
sentry issue list

# Or use the --log-level flag
sentry issue list --log-level debug

# Verbose output for API commands
sentry api /organizations/my-company/ --verbose

Next Steps

Authentication

Learn about all authentication commands and token management

Issue Commands

Explore all issue management and debugging commands

Project Commands

Learn how to list, view, and manage projects

API Access

Make direct API requests for advanced use cases

Get Started

Core Concepts

Guides

Quick Start Guide

Quick Start Guide

Prerequisites

Step 1: Authentication

OAuth Device Flow (Recommended)

API Token Authentication

Environment Variable Authentication

Self-Hosted Sentry

Step 2: Verify Authentication

Step 3: Explore Your Organizations and Projects

Step 4: Auto-Detect Your Project

Step 5: List Issues

Filter and Sort Issues

Step 6: Get AI-Powered Insights

Step 7: View Issue Details

Open in Browser

Step 8: View Event Details

Step 9: Export to JSON

Step 10: Make Direct API Requests

Common Workflows

Daily Issue Triage

CI/CD Integration

Monorepo Projects

Getting Help

Configuration Files

Logging and Debugging

Next Steps

Authentication

Issue Commands

Project Commands

API Access

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Quick Start Guide

​Prerequisites

​Step 1: Authentication

​OAuth Device Flow (Recommended)

​API Token Authentication

​Environment Variable Authentication

​Self-Hosted Sentry

​Step 2: Verify Authentication

​Step 3: Explore Your Organizations and Projects

​Step 4: Auto-Detect Your Project

​Step 5: List Issues

​Filter and Sort Issues

​Step 6: Get AI-Powered Insights

​Step 7: View Issue Details

​Open in Browser

​Step 8: View Event Details

​Step 9: Export to JSON

​Step 10: Make Direct API Requests

​Common Workflows

​Daily Issue Triage

​CI/CD Integration

​Monorepo Projects

​Getting Help

​Configuration Files

​Logging and Debugging

​Next Steps

Authentication

Issue Commands

Project Commands

API Access

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Step 1: Authentication

OAuth Device Flow (Recommended)

API Token Authentication

Environment Variable Authentication

Self-Hosted Sentry

Step 2: Verify Authentication

Step 3: Explore Your Organizations and Projects

Step 4: Auto-Detect Your Project

Step 5: List Issues

Filter and Sort Issues

Step 6: Get AI-Powered Insights

Step 7: View Issue Details

Open in Browser

Step 8: View Event Details

Step 9: Export to JSON

Step 10: Make Direct API Requests

Common Workflows

Daily Issue Triage

CI/CD Integration

Monorepo Projects

Getting Help

Configuration Files

Logging and Debugging

Next Steps