Configuration

The Sentry CLI can be configured through config files, environment variables, and a local database. Most users don't need to set any of these — the CLI auto-detects your project from your codebase and stores credentials locally after sentry auth login.

Environment Variables

SENTRY_AUTH_TOKEN

Authentication token for the Sentry API. This is the primary way to authenticate in CI/CD pipelines and scripts where interactive login is not possible.

You can create auth tokens in your Sentry account settings. When a stored OAuth login from sentry auth login also exists, the stored login is used by default and the env token acts as one more account: commands targeting an organization it can access (as listed by sentry org list) use it, and so does its own server when no stored login is on it. That requires its server to be known from a trusted source: an organization auth token's own URL, or sentry.io (a SENTRY_HOST/SENTRY_URL from the environment counts only when it is a sentry.io URL). For any other token on a self-hosted server, set SENTRY_FORCE_ENV_TOKEN=1. Set SENTRY_FORCE_ENV_TOKEN=1 to use only the env token.

export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

SENTRY_TOKEN

Legacy alias for SENTRY_AUTH_TOKEN. If both are set, SENTRY_AUTH_TOKEN takes precedence.

SENTRY_FORCE_ENV_TOKEN

When set to a truthy value (1, true, yes, on), environment variable tokens (SENTRY_AUTH_TOKEN / SENTRY_TOKEN) are the only credential used, overriding the stored OAuth token from sentry auth login and account selection. By default, the stored OAuth token takes priority because it supports automatic refresh, and the env token is only used for organizations it can access and for its own server. Set this if you want to ensure the environment variable token is always used, which is useful for self-hosted setups or CI environments.

export SENTRY_FORCE_ENV_TOKEN=1

SENTRY_ACCESS_TOKEN

Deprecated. Auth token for @sentry/mcp-server and sentry mcp only (the env form of the deprecated --access-token flag). It acts as SENTRY_AUTH_TOKEN and prints a deprecation warning; set that instead. Other commands ignore it.

export SENTRY_ACCESS_TOKEN=sntryu_YOUR_TOKEN_HERE

SENTRY_ORG

Default organization slug. Skips organization auto-detection.

export SENTRY_ORG=my-org

SENTRY_PROJECT

Default project slug. Can also include the org in org/project format.

When using the org/project combo format, SENTRY_ORG is ignored.

export SENTRY_PROJECT=my-org/my-project

SENTRY_DSN

Sentry DSN for project auto-detection. This is the same DSN you use in Sentry.init(). The CLI resolves it to determine your organization and project.

The CLI also detects DSNs from .env files and source code automatically — see DSN Auto-Detection.

export SENTRY_DSN=https://key@o123.ingest.us.sentry.io/456

SENTRY_RELEASE

Explicit release version for sentry release propose-version. When set, the command returns this value immediately without checking CI environment variables or local git history. Useful in CI pipelines where the release version is determined by a prior step.

export SENTRY_RELEASE=1.0.0

SENTRY_HOST

Base URL of your Sentry instance. Only needed for self-hosted Sentry. SaaS users (sentry.io) should not set this.

When set, all API requests are directed to this URL instead of https://sentry.io. Logging in to a self-hosted instance still requires sentry auth login --url <your-url>: the CLI refuses to log in to a self-hosted host that only comes from this variable. The CLI also sets this automatically when you pass a self-hosted Sentry URL as a command argument.

SENTRY_HOST takes precedence over SENTRY_URL. Both work identically — use whichever you prefer.

export SENTRY_HOST=https://sentry.example.com

SENTRY_URL

Alias for SENTRY_HOST. If both are set, SENTRY_HOST takes precedence.

SENTRY_CLIENT_ID

Client ID of a public OAuth application on your Sentry instance. Required for self-hosted Sentry (26.1.0+) to use sentry auth login with the device flow. See the Self-Hosted guide for how to create one.

export SENTRY_CLIENT_ID=your-oauth-client-id

SENTRY_SETUP_CODE

Private, short-lived code for headless OAuth authentication with sentry auth bootstrap or the installer. Each code can be redeemed once.

SENTRY_CUSTOM_HEADERS

Custom HTTP headers to include in all requests to your Sentry instance. Only applies to self-hosted Sentry. Ignored when targeting sentry.io.

Use semicolon-separated Name: Value pairs. Useful for environments behind reverse proxies that require additional headers for authentication (e.g., Google IAP, Cloudflare Access).

Can also be set persistently with sentry cli defaults headers.

export SENTRY_CUSTOM_HEADERS="X-IAP-Token: my-proxy-token"

SENTRY_CONFIG_DIR

Override the directory where the CLI stores its database (credentials, caches, defaults). Follows the XDG Base Directory specification: defaults to $XDG_CONFIG_HOME/sentry/ (i.e. ~/.config/sentry/ when XDG_CONFIG_HOME is unset). For backward compatibility, a pre-existing legacy ~/.sentry/ directory that contains cli.db is still used.

export SENTRY_CONFIG_DIR=/path/to/config

SENTRY_INSTALL_DIR

Override the directory where the CLI binary is installed. Used by the install script and sentry cli upgrade to control the binary location.

export SENTRY_INSTALL_DIR=/usr/local/bin

SENTRY_VERSION

Pin a specific version for the install script. Accepts a version number (e.g., 0.40.0) or nightly. The --version flag takes precedence if both are set.

This is useful in CI/CD pipelines and Dockerfiles where you want reproducible installations without inline flags.

export SENTRY_VERSION=nightly

SENTRY_INIT

Used with the install script. When set to 1, the installer runs sentry init after installing the binary, which prints the guide a coding agent follows to add Sentry to your project.

export SENTRY_INIT=1

SENTRY_NO_MODIFY_PATH

Used with the PowerShell install script (install.ps1). When set to 1, the installer leaves the user PATH unchanged. The bash install script takes the --no-modify-path flag instead.

export SENTRY_NO_MODIFY_PATH=1

SENTRY_GAMES_API_URL

Base URL of the service that serves the sentry games leaderboard scores. Defaults to https://games.sentry.new. Mainly useful for testing.

export SENTRY_GAMES_API_URL=http://localhost:8787

NODE_EXTRA_CA_CERTS

Path to a PEM file containing additional CA certificates to trust. Useful behind corporate TLS-intercepting proxies (Zscaler, Netskope, etc.).

Can also be set persistently with sentry cli defaults ca-cert.

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

SENTRY_PLAIN_OUTPUT

Force plain text output (no colors or ANSI formatting). Takes precedence over NO_COLOR. Set to 0 or false to force formatted output, even when piped.

export SENTRY_PLAIN_OUTPUT=1

SENTRY_NO_GRAPHICS

Disable inline terminal graphics (kitty and sixel) on terminals that support them; the banner falls back to block art, and image attachments printed by sentry api are written as raw bytes instead of rendered inline. You can also set this persistently with sentry cli defaults graphics off.

export SENTRY_NO_GRAPHICS=1

SENTRY_DISABLE_TIPS

Hide Tip: ... hints in command output. Other notices (pagination, dry-run, cache age) are still shown. Overrides the persistent sentry cli defaults tips setting.

export SENTRY_DISABLE_TIPS=1

SENTRY_NO_SIXEL

Deprecated alias for SENTRY_NO_GRAPHICS. Still honored for backward compatibility.

export SENTRY_NO_SIXEL=1

NO_COLOR

Standard convention to disable color output. See no-color.org. Respected when SENTRY_PLAIN_OUTPUT is not set.

export NO_COLOR=1

FORCE_COLOR

Force color output on interactive terminals. Only takes effect when stdout is a TTY. Set to 0 to force plain output, 1 to force color. Ignored when stdout is piped.

export FORCE_COLOR=1

SENTRY_OUTPUT_FORMAT

Force the output format for all commands. Currently only json is supported. This is primarily used by the library API (createSentrySDK()) to get JSON output without passing --json flags.

export SENTRY_OUTPUT_FORMAT=json

SENTRY_LOG_LEVEL

Controls the verbosity of diagnostic output. Defaults to info.

Valid values: error, warn, log, info, debug, trace

Equivalent to passing --log-level debug on the command line. CLI flags take precedence over the environment variable.

export SENTRY_LOG_LEVEL=debug

SENTRY_CLI_NO_TELEMETRY

Disable CLI telemetry (error tracking for the CLI itself). The CLI sends anonymized error reports to help improve reliability — set this to opt out.

export SENTRY_CLI_NO_TELEMETRY=1

DO_NOT_TRACK

Industry-standard opt-out for telemetry. When set to 1, the CLI disables all telemetry, equivalent to SENTRY_CLI_NO_TELEMETRY=1.

export DO_NOT_TRACK=1

SENTRY_PIPELINE

Identifies the Sentry build plugin that invoked the CLI (e.g., sentry-webpack-plugin/3.0.0). Used internally by sentry build upload to attribute uploads to the correct plugin. You typically don't need to set this manually — it is set automatically by Sentry build integrations.

SENTRY_CLI_NO_UPDATE_CHECK

Disable the automatic update check that runs periodically in the background.

export SENTRY_CLI_NO_UPDATE_CHECK=1

SENTRY_NO_CACHE

Disable API response caching. When set, the CLI will not cache API responses and will always make fresh requests.

export SENTRY_NO_CACHE=1

SENTRY_MAX_PAGINATION_PAGES

Cap the maximum number of pages fetched during auto-pagination. Useful for limiting API calls when using large --limit values.

export SENTRY_MAX_PAGINATION_PAGES=10

SENTRY_CLI_NO_AUTO_REPAIR

Disable automatic database schema repair. By default, the CLI automatically repairs its SQLite database when it detects schema drift, including clearing cached data a newer CLI version wrote. Set this to 1 to prevent auto-repair; sentry cli fix still repairs on demand.

export SENTRY_CLI_NO_AUTO_REPAIR=1

Configuration File (.sentryclirc)

The CLI supports a .sentryclirc config file using standard INI syntax. This is the same format used by the legacy sentry-cli tool, so existing config files are automatically picked up.

How It Works

The CLI looks for .sentryclirc files by walking up from your current directory toward the filesystem root. If multiple files are found, values from the closest file take priority, with ~/.sentryclirc serving as a global fallback.

[defaults]
org = my-org
project = my-project

[auth]
token = sntrys_...

Supported Fields

Section	Key	Description
[defaults]	org	Default organization slug
[defaults]	project	Default project slug
[defaults]	url	Sentry base URL (for self-hosted)
[auth]	token	Auth token (mapped to SENTRY_AUTH_TOKEN)

Monorepo Setup

In monorepos, place a .sentryclirc at the repo root with your org, then add per-package configs with just the project:

my-monorepo/
  .sentryclirc              # [defaults] org = my-company
  packages/
    frontend/
      .sentryclirc          # [defaults] project = frontend-web
    backend/
      .sentryclirc          # [defaults] project = backend-api

When you run a command from packages/frontend/, the CLI resolves org = my-company from the root and project = frontend-web from the closest file.

Resolution Priority

When the CLI needs to determine your org and project, it checks these sources in order:

1. Explicit CLI arguments — sentry issue list my-org/my-project
2. Environment variables — SENTRY_ORG / SENTRY_PROJECT
3. .sentryclirc config file — walked up from CWD, merged with ~/.sentryclirc
4. Persistent defaults — set via sentry cli defaults
5. DSN auto-detection — scans source code and .env files
6. Directory name inference — matches your directory name against project slugs
7. Your account — when you can reach exactly one organization, it is used. Commands that need a project also need that organization to have exactly one project

The first source that provides both org and project wins. For org-only commands, only the org is needed.

Full issue short IDs, such as sentry issue view FRONT-ABC, only need the org: SENTRY_ORG, .sentryclirc, and persistent defaults scope the lookup in that order. Use sentry issue view other-org/FRONT-ABC to override the configured organization. Project aliases retain their associated organization. See View an issue.

Backward Compatibility

If you previously used the legacy sentry-cli and have a ~/.sentryclirc file, the new CLI reads it automatically. The [defaults] and [auth] sections are fully compatible. The [auth] token value is mapped to the SENTRY_AUTH_TOKEN environment variable internally (only if the env var is not already set).

Persistent Defaults

Use sentry cli defaults to set persistent defaults for organization, project, URL, custom headers, CA certificate, telemetry, agent skills, inline graphics, and tips. These are stored in the CLI's local database and apply to all commands.

sentry cli defaults org my-org           # Set default organization
sentry cli defaults project my-project   # Set default project
sentry cli defaults url https://...      # Set Sentry URL (self-hosted)
sentry cli defaults telemetry off        # Disable telemetry
sentry cli defaults tips off             # Hide Tip: hints in command output
sentry cli defaults                      # Show all current defaults
sentry cli defaults org --clear          # Clear a specific default

See sentry cli defaults for full usage.

Disabling tips

Some commands print a Tip: ... hint below their output. To hide these, store the preference or set an environment variable:

sentry cli defaults tips off   # persistent
export SENTRY_DISABLE_TIPS=1   # per-session, overrides the stored preference

Only the tips are removed. Pagination hints, dry-run and cancellation notices, and the cache-age footer (cached · 3m ago · use -f to refresh) are still shown.

Telemetry

The CLI sends usage data and error reports about itself to Sentry. To opt out, set SENTRY_CLI_NO_TELEMETRY=1 or DO_NOT_TRACK=1, or run sentry cli defaults telemetry off.

When telemetry can't be sent, for example while offline or when a firewall blocks Sentry, the CLI keeps it in its local database and sends up to 10 stored envelopes on each later run. The cache holds at most 100 envelopes and 4 MiB, compressed. When it's full, the oldest usage data goes first, then the oldest error reports. It discards error reports after 30 days and everything else after 4 days. Metrics, such as timings, aren't cached: when they can't be sent, they're dropped.

After the first failed send, the CLI stops sending for 5 minutes, so an unreachable Sentry delays a command's exit by about 3 seconds at most. Long-running commands, such as sentry mcp and sentry local, then try one send every 5 minutes, and send up to 10 stored envelopes once one succeeds.

Opting out deletes the cache on the next run. The library (createSentrySDK) never caches telemetry.

Global Options

These flags are accepted by every command. They are not shown in individual command --help output, but are always available.

--log-level <level>

Set the log verbosity level. Accepts: error, warn, log, info, debug, trace.

sentry issue list --log-level debug
sentry --log-level=trace cli upgrade

Overrides SENTRY_LOG_LEVEL when both are set.

--verbose

Shorthand for --log-level debug. Enables debug-level diagnostic output.

sentry issue list --verbose

Note

The sentry api command also uses --verbose to show full HTTP request/response details. When used with sentry api, it serves both purposes (debug logging + HTTP output).

Credential Storage

We store credentials and caches in a SQLite database (cli.db) inside the config directory. The location follows the XDG Base Directory specification: by default the CLI uses $XDG_CONFIG_HOME/sentry (i.e. ~/.config/sentry/ when XDG_CONFIG_HOME is unset), and you can override it with SENTRY_CONFIG_DIR. For backward compatibility, if a legacy ~/.sentry/ directory already exists it continues to be used. The database file and its WAL side-files are created with restricted permissions (mode 600) so that only the current user can read them. The database also caches:

• Organization and project defaults
• DSN resolution results
• Region URL mappings
• Project aliases (for monorepo support)

API responses are cached separately, as compressed files under cache/api-responses/ in the same config directory. Commands that accept --fresh (-f) skip cached responses for that run; set SENTRY_NO_CACHE=1 to turn the cache off entirely.

See Credential Storage in the auth command docs for more details.

Binary Install Location

When installed via the install script, the CLI binary is placed in an XDG-aligned directory. sentry cli setup resolves the location in this order:

1. SENTRY_INSTALL_DIR — explicit override
2. $XDG_BIN_HOME — used when set to an absolute path, per the XDG spec
3. ~/.local/bin or ~/bin — when either already exists and is on your PATH
4. ~/.local/bin — default fallback

Older installs placed the binary in ~/.sentry/bin. Running sentry cli setup moves an existing ~/.sentry/bin binary into the resolved install directory (updating your PATH and recorded install metadata to match) and migrates any legacy ~/.sentry config data (cli.db, config.json) into the XDG config directory. Both migrations are skipped when a binary or config already exists at the target.

sentry cli upgrade runs setup on the new binary, so it migrates too — but conservatively, because upgrade never edits your PATH. A legacy ~/.sentry/bin binary is relocated to the XDG install directory only when that directory is already on your PATH, so the moved binary stays discoverable. If the XDG directory isn't on PATH, upgrade leaves the binary in place (a mislocated binary that vanished from PATH would break the command); run sentry cli setup explicitly to relocate it and update PATH. Legacy config data is migrated on upgrade regardless.