Development Guide

Prerequisites

Node.js v22.15+ installed
pnpm v10.11+ installed

A Sentry OAuth application (create one at https://sentry.io/settings/account/api/applications/)

Setup

Install dependencies:

pnpm install

Create a .env.local file in the project root:

SENTRY_CLIENT_ID=your-sentry-oauth-client-id

Get the client ID from your Sentry OAuth application settings.

Note: No client secret is needed - the CLI uses OAuth 2.0 Device Authorization Grant (RFC 8628) which is designed for public clients.

Running Locally

Load environment variables from .env.local (e.g. via dotenv or export $(cat .env.local | xargs)), then:

pnpm run cli -- auth login

Testing the Device Flow

Run the CLI login command:

pnpm run cli -- auth login

You'll see output like:

Starting authentication...

Opening browser...
If it doesn't open, visit: https://sentry.io/oauth/device/
Code: ABCD-EFGH

Waiting for authorization...

The browser will open to Sentry's device authorization page
Enter the code and authorize the application
The CLI will automatically receive the token and save it

Sentry OAuth App Configuration

When creating your Sentry OAuth application:

Redirect URI: Not required for device flow
Scopes: The CLI requests these scopes:

project:read, project:write, project:admin
org:read
event:read, event:write
member:read
team:read, team:write

Environment Variables

The table below lists the most common development variables. For the complete reference, see the generated Configuration page.

Variable	Description	Default
`SENTRY_AUTH_TOKEN`	API token for non-interactive use (lower priority than stored OAuth by default)	—
`SENTRY_FORCE_ENV_TOKEN`	Force env token to take priority over stored OAuth token	—
`SENTRY_HOST`	Sentry instance URL (for self-hosted, takes precedence)	`https://sentry.io`
`SENTRY_URL`	Alias for `SENTRY_HOST`	`https://sentry.io`
`SENTRY_CLIENT_ID`	Sentry OAuth app client ID	(required for build)
`SENTRY_CONFIG_DIR`	Override credentials/cache directory	`~/.sentry/`
`SENTRY_LOG_LEVEL`	Diagnostic log level (`error`, `warn`, `log`, `info`, `debug`, `trace`)	`info`
`SENTRY_CLI_NO_TELEMETRY`	Disable CLI telemetry (error tracking)	—

Building

Build the native binary (uses esbuild for bundling and fossilize for Node SEA packaging):

pnpm run build

Architecture

The CLI uses the OAuth 2.0 Device Authorization Grant (RFC 8628) for authentication. This flow is designed for CLI tools and other devices that can't easily handle browser redirects:

CLI requests a device code from Sentry
User is shown a code and URL to visit
CLI polls Sentry until the user authorizes
CLI receives access token and stores it locally

No proxy server is needed - the CLI communicates directly with Sentry.