- A Sentry OAuth application client ID for builds, self-hosted Sentry, or a custom OAuth app (create one at https://sentry.io/settings/account/api/applications/)
- Install dependencies:
pnpm install- Optionally, create
packages/cli/.env.local(see.env.example):
SENTRY_CLIENT_ID=your-sentry-oauth-client-id
Dev mode (pnpm run cli), pnpm run build and pnpm run bundle fall back to the CLI's public sentry.io client ID when SENTRY_CLIENT_ID is unset. Set it to use self-hosted Sentry or your own OAuth app. 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.
pnpm run cli loads .env.local automatically when it exists:
pnpm run cli auth login- 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
When creating your Sentry OAuth application:
- Redirect URI: Not required for device flow
- Scopes: The CLI requests these scopes:
project:read,project:write,project:adminorg:read,org:integrationsevent:read,event:writemember:readteam:read,team:write,team:adminalerts:read,alerts:write
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 | Public sentry.io client ID |
SENTRY_SETUP_CODE |
One-time setup code for headless authentication | — |
SENTRY_CONFIG_DIR |
Override credentials/cache directory (XDG default: ~/.config/sentry/) | ~/.config/sentry/ |
SENTRY_LOG_LEVEL |
Diagnostic log level (error, warn, log, info, debug, trace) |
info |
SENTRY_CLI_NO_TELEMETRY |
Disable CLI telemetry (error tracking) | — |
Build the native binary (uses esbuild for bundling and fossilize for Node SEA packaging):
pnpm run buildsentry schema reads the index generated by pnpm run generate:schema from
the installed @sentry/api version. New operations and query enum values become
searchable when this index is regenerated; do not add a separate vocabulary map.
The generator reads @sentry/api/operations directly, without fetching a schema
or parsing the SDK bundle. The SDK owns operation metadata; the CLI preserves
its resource grouping and JSON output format when projecting the catalog.
pnpm run generate:command-api uses @sentry/api/source-analysis to follow command
implementations and their helpers, generating API relationships from SDK calls
and recognized raw request paths. The CLI supplies its command builders, request
wrappers, and query context; it also reuses this analysis for DELETE checks.
Keep dataset and filter values in the requests themselves; do not add a
parallel list of operation names or command vocabulary. Build diagnostics report
raw or unpublished calls that the generated catalog cannot identify, so the
relationships describe discovered usage rather than exhaustive coverage.
Introspection derives canonical command paths, registered aliases, and group membership from the route tree. Groups collect their public commands' generated references, so adding a command requires no separate group mapping. A related API does not reproduce the command's complete request orchestration, pagination, or transformations.
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.
src/lib/sentry-client.ts owns the CLI's single retry budget: at most three
attempts, shared by transient HTTP statuses, network failures, and interrupted
successful GET bodies. Finite GET bodies finish inside the attempt timeout.
JSON parsing and response validation happen afterward; malformed JSON does not
trigger another request. Successful mutations are not replayed for body errors.
Generated API operations use getSdkClientConfig from
src/lib/sentry-sdk-client.ts. Its request interceptor passes the SDK's
parseAs intent to the transport before the SDK calls fetch(Request).
Explicit streams, automatic parsing without a Content-Type, and SSE remain
streaming. Handwritten helpers that consume complete responses opt in through
bufferResponseBody.
When creating a bound createSentryClient instead, register
registerSdkResponseBodyMode(sentry.client) once on that client's transport.
Passing an existing client in its constructor config does not transfer
interceptors. Keep the runtime SDK import outside sentry-client.ts, which is
also loaded synchronously by telemetry's database integration.
When telemetry is enabled, is_ci records true or false for each invocation,
independently of the agent and is_tty tags. CI detection reuses the environment
variable detector used for VCS metadata collection, including CI and known
provider markers. Telemetry records the detection result without sending raw
environment variable values. The signals can overlap: an agent running in CI
retains its agent identity and also has is_ci:true.
For command usage widgets, retain the existing base query:
!span.description:cli-execution !span.description:[sentry.auth.login,sentry.auth.logout,sentry.auth.refresh] span.op:cli.command
Keep the count(span.duration) aggregate and append the relevant condition:
| Segment | Additional condition |
|---|---|
| Agent | !agent:"" |
| CI | agent:"" is_ci:true |
| Human | agent:"" is_ci:false |
| Unknown | agent:"" is_ci:"" |
These segments give detected agents priority, including agents running in CI.
To inspect that subset, append !agent:"" is_ci:true to the base query.
The Human label remains an approximation: no detected CI or agent does not prove
human execution; local scripts and undetected agents can also fall into this
segment. Older telemetry without is_ci stays Unknown when no agent was detected.
Do not treat an absent is_ci tag as false.
Update usage dashboards after releasing the CLI version that emits is_ci.