Skip to content

Latest commit

 

History

History
193 lines (143 loc) · 7.81 KB

DEVELOPMENT.md

File metadata and controls

193 lines (143 loc) · 7.81 KB

Development Guide

Prerequisites

Setup

  1. Install dependencies:
pnpm install
  1. 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.

Running Locally

pnpm run cli loads .env.local automatically when it exists:

pnpm run cli auth login

Testing the Device Flow

  1. Run the CLI login command:
pnpm run cli auth login
  1. 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...
  1. The browser will open to Sentry's device authorization page
  2. Enter the code and authorize the application
  3. 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, org:integrations
  • event:read, event:write
  • member:read
  • team:read, team:write, team:admin
  • alerts:read, alerts: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 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) —

Building

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

pnpm run build

Architecture

API discovery references

sentry 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.

Authentication

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:

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

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

API response retries

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.

Invocation telemetry

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.