Skip to main content
The Sentry CLI stores its configuration, authentication tokens, and cached data in a local SQLite database. This page documents the database structure, cache behavior, and file locations.

​
Database Location

The configuration database is stored at:
  • Linux/macOS: ~/.config/sentry-cli/config.db
  • Windows: %APPDATA%\sentry-cli\config.db
You can override this location by setting the SENTRY_CONFIG_DIR environment variable: 
export SENTRY_CONFIG_DIR=/path/to/custom/config

​
Database Schema

The CLI uses SQLite with a versioned schema system. The current schema version is 8.

​
Core Tables

​
schema_version

Tracks the current database schema version for migrations. 
CREATE TABLE IF NOT EXISTS schema_version (
    version INTEGER PRIMARY KEY
)

​
auth

Stores OAuth authentication tokens (single-row table). 
CREATE TABLE IF NOT EXISTS auth (
    id INTEGER PRIMARY KEY CHECK (id = 1),
    token TEXT,
    refresh_token TEXT,
    expires_at INTEGER,
    issued_at INTEGER,
    updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
)
  • id: Always 1 (enforced by CHECK constraint)
  • token: OAuth access token
  • refresh_token: OAuth refresh token for automatic renewal
  • expires_at: Token expiration timestamp (milliseconds since epoch)
  • issued_at: Token issue timestamp (milliseconds since epoch)
  • updated_at: Last update timestamp (auto-managed)
Token Refresh: Tokens are automatically refreshed when less than 10% of their lifetime remains (configurable via REFRESH_THRESHOLD constant). Default token lifetime is 1 hour.

​
defaults

Stores default organization and project (single-row table). 
CREATE TABLE IF NOT EXISTS defaults (
    id INTEGER PRIMARY KEY CHECK (id = 1),
    organization TEXT,
    project TEXT,
    updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
)
  • organization: Default organization slug
  • project: Default project slug
  • updated_at: Last update timestamp (auto-managed)

​
user_info

Caches authenticated user information (single-row table). 
CREATE TABLE IF NOT EXISTS user_info (
    id INTEGER PRIMARY KEY CHECK (id = 1),
    user_id TEXT NOT NULL,
    email TEXT,
    username TEXT,
    name TEXT,
    updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
)

​
instance_info

Stores a unique instance ID for telemetry (single-row table). 
CREATE TABLE IF NOT EXISTS instance_info (
    id INTEGER PRIMARY KEY CHECK (id = 1),
    instance_id TEXT NOT NULL,
    created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
)

​
Cache Tables

​
project_cache

Caches project metadata from the Sentry API. 
CREATE TABLE IF NOT EXISTS project_cache (
    cache_key TEXT PRIMARY KEY,
    org_slug TEXT NOT NULL,
    org_name TEXT NOT NULL,
    project_slug TEXT NOT NULL,
    project_name TEXT NOT NULL,
    project_id TEXT,
    cached_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
    last_accessed INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
)
  • cache_key: Composite key (typically org_slug/project_slug)
  • project_id: Numeric project ID (added in schema version 7)
  • No TTL: Cache entries remain valid indefinitely and are updated on access

​
dsn_cache

Caches DSN resolution results (maps DSNs to org/project information). 
CREATE TABLE IF NOT EXISTS dsn_cache (
    directory TEXT PRIMARY KEY,
    dsn TEXT NOT NULL,
    project_id TEXT NOT NULL,
    org_id TEXT,
    source TEXT NOT NULL,
    source_path TEXT,
    resolved_org_slug TEXT,
    resolved_org_name TEXT,
    resolved_project_slug TEXT,
    resolved_project_name TEXT,
    fingerprint TEXT,
    all_dsns_json TEXT,
    source_mtimes_json TEXT,
    dir_mtimes_json TEXT,
    root_dir_mtime INTEGER,
    ttl_expires_at INTEGER,
    cached_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
    last_accessed INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
)
  • source: Detection source (e.g., .env, src/index.js)
  • fingerprint: Content hash for invalidation
  • *_json: JSON-encoded metadata for change detection
  • ttl_expires_at: Time-based expiration (added in schema version 4)

​
project_root_cache

Caches project root detection results. 
CREATE TABLE IF NOT EXISTS project_root_cache (
    cwd TEXT PRIMARY KEY,
    project_root TEXT NOT NULL,
    reason TEXT NOT NULL,
    cwd_mtime INTEGER NOT NULL,
    cached_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
    ttl_expires_at INTEGER NOT NULL
)
  • cwd: Working directory used as cache key
  • reason: Detection method (e.g., .git, package.json)
  • cwd_mtime: Directory modification time for invalidation

​
project_aliases

Stores short aliases for projects (used in monorepos). 
CREATE TABLE IF NOT EXISTS project_aliases (
    alias TEXT PRIMARY KEY,
    org_slug TEXT NOT NULL,
    project_slug TEXT NOT NULL,
    dsn_fingerprint TEXT,
    cached_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
    last_accessed INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
)

​
org_regions

Caches organization region URLs (for multi-region support). 
CREATE TABLE IF NOT EXISTS org_regions (
    org_slug TEXT PRIMARY KEY,
    org_id TEXT,
    region_url TEXT NOT NULL,
    updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
)
  • org_id: Numeric organization ID (added in schema version 8)
  • region_url: Regional API endpoint (e.g., https://us.sentry.io)

​
pagination_cursors

Caches pagination cursors for --cursor last support. 
CREATE TABLE IF NOT EXISTS pagination_cursors (
    command_key TEXT NOT NULL,
    context TEXT NOT NULL,
    cursor TEXT NOT NULL,
    expires_at INTEGER NOT NULL,
    PRIMARY KEY (command_key, context)
)
  • TTL: 5 minutes (ephemeral)
  • Composite primary key: Added in schema version 6

​
metadata

Generic key-value store for CLI metadata. 
CREATE TABLE IF NOT EXISTS metadata (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL
)
Currently used for:
  • Version check timestamps
  • Last upgrade notification

​
Schema Migrations

The CLI automatically migrates the database schema when you upgrade to a new version.

​
Migration History

VersionChanges
1 → 2Added org_regions, user_info, instance_info tables
2 → 3Added name column to user_info
3 → 4Added detection caching columns to dsn_cache, added project_root_cache
4 → 5Added pagination_cursors table
5 → 6Fixed pagination_cursors composite primary key
6 → 7Added project_id column to project_cache
7 → 8Added org_id column to org_regions

​
Auto-Repair

If the CLI detects schema issues (missing tables or columns), it automatically repairs them. This is useful when:
  • The database was corrupted
  • A previous migration failed
  • The database was manually modified
To disable auto-repair: 
export SENTRY_CLI_NO_AUTO_REPAIR=1

​
Cache TTLs

The CLI uses different cache strategies for different data types:
  • Authentication tokens: Refreshed when < 10% of lifetime remains (default: 1 hour)
  • Pagination cursors: 5 minutes (hardcoded)
  • Project metadata: No expiration (updated on access)
  • DSN resolution: Content-based invalidation via fingerprints + optional TTL
  • Project root: Content-based invalidation via directory mtime + TTL
  • Organization regions: No expiration (updated on access)

​
Database Maintenance

​
Manual Inspection

You can inspect the database using any SQLite client: 
sqlite3 ~/.config/sentry-cli/config.db

-- View current schema version
SELECT version FROM schema_version;

-- Check authentication status
SELECT token IS NOT NULL AS authenticated,
       expires_at,
       datetime(expires_at/1000, 'unixepoch') AS expires
FROM auth WHERE id = 1;

-- View default org/project
SELECT organization, project FROM defaults WHERE id = 1;

-- List cached projects
SELECT org_slug, project_slug, project_name
FROM project_cache
ORDER BY last_accessed DESC;

​
Clear All Data

To reset the CLI to a clean state, delete the entire config directory: 
rm -rf ~/.config/sentry-cli/
The CLI will automatically recreate the database on next run.

​
Clear Specific Data

Use the sentry auth logout command to clear authentication data (also clears user info, org regions, and pagination cursors): 
sentry auth logout

​
Database Errors

If you encounter database errors:
  1. Check permissions: Ensure the CLI can write to ~/.config/sentry-cli/
  2. Check disk space: SQLite requires free space for temporary files
  3. Try auto-repair: The CLI will attempt to fix schema issues automatically
  4. Manual reset: Delete the database file and let the CLI recreate it
Common error messages:
  • attempt to write a readonly database: Check file/directory permissions
  • no such table: Schema is corrupted, auto-repair should fix it
  • no such column: Schema is outdated, auto-repair should fix it
See the Troubleshooting page for detailed error solutions.

Build docs developers (and LLMs) love

Get started for freeTalk to us