Configuration

Sentry CLI stores configuration in a local SQLite database and reads settings from environment variables. This guide covers how to customize the configuration to suit your workflow.

Configuration Directory

The CLI stores all persistent data in a configuration directory:

# Default location
~/.sentry/

# Contains:
~/.sentry/cli.db          # SQLite database
~/.sentry/cli.db-wal      # Write-ahead log
~/.sentry/cli.db-shm      # Shared memory file

Custom Configuration Directory

You can change the config directory with SENTRY_CONFIG_DIR:

# Use a custom directory
export SENTRY_CONFIG_DIR=~/my-custom-sentry-config
sentry auth login

Separate profiles
SaaS vs Self-Hosted
Project-local config

# Personal account
export SENTRY_CONFIG_DIR=~/.sentry-personal
sentry auth login

# Work account
export SENTRY_CONFIG_DIR=~/.sentry-work
sentry auth login

# Switch between them
export SENTRY_CONFIG_DIR=~/.sentry-work
sentry org list

# SaaS configuration
export SENTRY_CONFIG_DIR=~/.sentry-saas
unset SENTRY_URL
sentry auth login

# Self-hosted configuration
export SENTRY_CONFIG_DIR=~/.sentry-selfhosted
export SENTRY_URL=https://sentry.example.com
sentry auth login

# Store config in project directory
export SENTRY_CONFIG_DIR=./.sentry-config
sentry auth login

# Add to .gitignore
echo ".sentry-config" >> .gitignore

Directory Permissions

The config directory is created with secure permissions:

# Directory: 0700 (rwx------)
# Database:  0600 (rw-------)

This ensures only your user can read authentication tokens.

The database contains sensitive authentication tokens. Never commit it to version control or share it.

Database

The CLI uses SQLite to store:

Authentication: OAuth tokens, expiry times, refresh tokens
User info: Email, name, user ID
Defaults: Default organization and project
Cache: Organization regions, project metadata, DSN lookups
Pagination: Cursor state for paginated list commands

Database Schema

Key tables:

Table	Purpose
`auth`	OAuth tokens and expiry
`user_info`	Cached user profile
`defaults`	Default org/project
`org_regions`	Org to region URL mapping
`project_cache`	Project metadata cache
`dsn_cache`	DSN to org/project resolution
`pagination_cursors`	List command cursors
`instance_info`	Installation UUID (telemetry)

Cache TTL

Most caches expire after 7 days. The CLI automatically cleans up expired entries (10% probability on each write). To force cache refresh:

# Delete the database to clear all caches
rm ~/.sentry/cli.db*

# Next command will rebuild the cache
sentry org list

Database Corruption

If the database becomes corrupted:

Error: SQLite error: database disk image is malformed

Remove the database and it will be recreated:

rm ~/.sentry/cli.db*
sentry auth login

Deleting the database logs you out. You’ll need to authenticate again.

Default Organization and Project

Set defaults to avoid typing org/project on every command:

# Set default organization
sentry config default-org my-org

# Set default project
sentry config default-project my-project

# Now commands use these defaults
sentry issue list              # Uses default org/project
sentry project view            # Uses default project

When Defaults Are Used

Defaults apply when:

No org/project specified in arguments
No DSN detected in current directory
No --org or --project flags provided

Precedence

Explicit arguments: sentry issue list my-org/my-project
Flags: --org my-org --project my-project
DSN auto-detection: From .env or source code
Defaults: Stored in database

Viewing Defaults

# Show current configuration
sentry config show

# Output:
# Default organization: my-org
# Default project: my-project

Clearing Defaults

# Clear default organization
sentry config default-org --clear

# Clear default project
sentry config default-project --clear

Environment Variables

Authentication

SENTRY_AUTH_TOKEN

string

Authentication token. Takes priority over SENTRY_TOKEN and stored OAuth tokens.

export SENTRY_AUTH_TOKEN=sntrys_YourTokenHere
sentry org list

SENTRY_TOKEN

string

Alternative authentication token. Used if SENTRY_AUTH_TOKEN is not set.

export SENTRY_TOKEN=sntrys_YourTokenHere
sentry org list

Token precedence: SENTRY_AUTH_TOKEN > SENTRY_TOKEN > stored OAuth token

Self-Hosted Configuration

SENTRY_URL

string

Base URL for self-hosted Sentry instances. Defaults to https://sentry.io.

export SENTRY_URL=https://sentry.example.com
sentry org list

See the Self-Hosted guide for details.

SENTRY_CLIENT_ID

string

OAuth client ID for self-hosted instances. Required for OAuth device flow on self-hosted Sentry 26.1.0+.

export SENTRY_CLIENT_ID=your-client-id
sentry auth login

SENTRY_CONFIG_DIR

string

Directory for storing CLI configuration and database. Defaults to ~/.sentry.

export SENTRY_CONFIG_DIR=~/.sentry-work
sentry auth login

Logging and Debugging

SENTRY_LOG_LEVEL

string

Log level for CLI output. Options: error, warn, info (default), debug, trace.

# Enable debug logging
SENTRY_LOG_LEVEL=debug sentry issue list

# Trace all HTTP requests
SENTRY_LOG_LEVEL=trace sentry org list 2>debug.log

NO_COLOR

string

Disable colored output. Set to any value to disable.

NO_COLOR=1 sentry issue list

SENTRY_PLAIN_OUTPUT

string

Force plain text output (no colors, no ANSI). Useful for non-TTY environments.

SENTRY_PLAIN_OUTPUT=1 sentry issue list

Telemetry

SENTRY_TELEMETRY_DISABLED

string

Disable error and performance telemetry. Set to 1 or true to disable.

export SENTRY_TELEMETRY_DISABLED=1
sentry org list

The CLI sends errors and performance data to Sentry to help improve the product. Disabling telemetry opts you out.

Common Configuration Patterns

Multi-Account Setup

Manage multiple Sentry accounts with shell aliases:

~/.bashrc

# Personal account (SaaS)
alias sentry-personal='SENTRY_CONFIG_DIR=~/.sentry-personal sentry'

# Work account (SaaS)
alias sentry-work='SENTRY_CONFIG_DIR=~/.sentry-work sentry'

# Self-hosted
alias sentry-sh='SENTRY_CONFIG_DIR=~/.sentry-selfhosted SENTRY_URL=https://sentry.example.com sentry'

Usage:

sentry-personal org list
sentry-work issue list
sentry-sh project list

Project-Local Configuration

Store Sentry config in your project:

Create local config directory

mkdir .sentry-config
echo ".sentry-config" >> .gitignore

Set environment variable

.env.local

SENTRY_CONFIG_DIR=./.sentry-config
SENTRY_AUTH_TOKEN=your-token

Use in scripts

deploy.sh

#!/bin/bash
set -a
source .env.local
set +a

sentry org list
sentry issue list

CI/CD Configuration

Best practices for CI/CD:

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      # Use token auth (not OAuth) in CI
      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
      # Optional: self-hosted
      # SENTRY_URL: https://sentry.example.com
      # Disable interactive prompts
      CI: true
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @sentry/cli-next
      - run: sentry project list --json

Never hardcode tokens in CI config. Always use secrets/credentials management.

Development vs Production

Separate configs for different environments:

# Development (local OAuth)
export SENTRY_CONFIG_DIR=~/.sentry-dev
export SENTRY_URL=https://sentry-dev.example.com
sentry auth login

# Production (token from secrets manager)
export SENTRY_AUTH_TOKEN=$(aws secretsmanager get-secret-value --secret-id sentry-token --query SecretString --output text)
export SENTRY_URL=https://sentry.example.com
sentry issue list

Debugging Configuration Issues

Check effective configuration

# Show auth status and source
sentry auth status

# Show defaults
sentry config show

# Show all Sentry environment variables
env | grep SENTRY_

Enable debug logging

# See all HTTP requests
SENTRY_LOG_LEVEL=debug sentry org list 2>&1 | grep -i http

# Trace database operations
SENTRY_LOG_LEVEL=trace sentry config show 2>trace.log

Test token validity

# Set token explicitly
export SENTRY_AUTH_TOKEN=your-token

# Test access
sentry auth status

# If successful, token is valid
# If error, token is invalid or expired

Check database location

# Find current database
if [ -n "$SENTRY_CONFIG_DIR" ]; then
  echo "Using: $SENTRY_CONFIG_DIR/cli.db"
else
  echo "Using: ~/.sentry/cli.db"
fi

# Check if it exists
ls -lh ~/.sentry/cli.db*

Reset configuration

If configuration is broken:

# Backup current config
mv ~/.sentry ~/.sentry.backup

# Reconfigure from scratch
sentry auth login
sentry config default-org my-org
sentry config default-project my-project

Security Best Practices

Never commit the config directory

.gitignore

# Sentry CLI config
.sentry-config/
~/.sentry/

Use environment variables in CI

# ✅ Good: Use secrets
env:
  SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}

# ❌ Bad: Hardcode tokens
env:
  SENTRY_AUTH_TOKEN: sntrys_abc123...

Restrict token scopes

When creating auth tokens, only grant necessary scopes:Read-only access:

project:read
org:read
event:read

CI/CD deployment:

project:read
project:write
org:read

Rotate tokens regularly

# Create new token in Sentry UI
# Update in secrets manager
aws secretsmanager update-secret \
  --secret-id sentry-token \
  --secret-string "new-token-here"

# Revoke old token in Sentry UI

Use separate configs for work accounts

# Personal: ~/.sentry-personal
# Work: ~/.sentry-work
# Never mix credentials

This prevents accidentally using work credentials for personal projects.

Get Started

Core Concepts

Guides

Configuration

Configuration Directory

Custom Configuration Directory

Directory Permissions

Database

Database Schema

Cache TTL

Database Corruption

Default Organization and Project

When Defaults Are Used

Precedence

Viewing Defaults

Clearing Defaults

Environment Variables

Authentication

Self-Hosted Configuration

Configuration

Logging and Debugging

Telemetry

Common Configuration Patterns

Multi-Account Setup

Project-Local Configuration

CI/CD Configuration

Development vs Production

Debugging Configuration Issues

Check effective configuration

Enable debug logging

Test token validity

Check database location

Reset configuration

Security Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Configuration Directory

​Custom Configuration Directory

​Directory Permissions

​Database

​Database Schema

​Cache TTL

​Database Corruption

​Default Organization and Project

​When Defaults Are Used

​Precedence

​Viewing Defaults

​Clearing Defaults

​Environment Variables

​Authentication

​Self-Hosted Configuration

​Configuration

​Logging and Debugging

​Telemetry

​Common Configuration Patterns

​Multi-Account Setup

​Project-Local Configuration

​CI/CD Configuration

​Development vs Production

​Debugging Configuration Issues

​Check effective configuration

​Enable debug logging

​Test token validity

​Check database location

​Reset configuration

​Security Best Practices

Build docs developers (and LLMs) love

Configuration Directory

Custom Configuration Directory

Directory Permissions

Database

Database Schema

Cache TTL

Database Corruption

Default Organization and Project

When Defaults Are Used

Precedence

Viewing Defaults

Clearing Defaults

Environment Variables

Authentication

Self-Hosted Configuration

Configuration

Logging and Debugging

Telemetry

Common Configuration Patterns

Multi-Account Setup

Project-Local Configuration

CI/CD Configuration

Development vs Production

Debugging Configuration Issues

Check effective configuration

Enable debug logging

Test token validity

Check database location

Reset configuration

Security Best Practices