feat: support SENTRY_HOST as alias for SENTRY_URL (#409)

## Summary

Adds `SENTRY_HOST` as a supported env var for configuring the Sentry
instance URL. It takes precedence over `SENTRY_URL` so both work, but
users who expect `SENTRY_HOST` (common in other Sentry tooling) get the
behavior they want out of the box.

Precedence: `SENTRY_HOST` > `SENTRY_URL` > default (`https://sentry.io`)

## Changes

A single `getConfiguredSentryUrl()` helper in `constants.ts` replaces
all 8 `process.env.SENTRY_URL` reads across 6 source files.
`applySentryUrlContext()` now sets/deletes both env vars so
`SENTRY_HOST` can't shadow a freshly-set `SENTRY_URL`.

## Test plan

- New tests for `SENTRY_HOST` alone and precedence over `SENTRY_URL` in
region, code-scanner, URL parser, and URL builder tests
- All 146 tests across the 4 modified test files pass
- `bun run typecheck` and `bun run lint` clean


🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: betegon

DEVELOPMENT.md

@@ -67,10 +67,11 @@ When creating your Sentry OAuth application:
 
 ## Environment Variables
 
-| Variable           | Description                          | Default              |
-| ------------------ | ------------------------------------ | -------------------- |
-| `SENTRY_CLIENT_ID` | Sentry OAuth app client ID           | (required)           |
-| `SENTRY_URL`       | Sentry instance URL (for self-hosted)| `https://sentry.io`  |
+| Variable           | Description                                           | Default              |
+| ------------------ | ----------------------------------------------------- | -------------------- |
+| `SENTRY_CLIENT_ID` | Sentry OAuth app client ID                            | (required)           |
+| `SENTRY_HOST`      | Sentry instance URL (for self-hosted, takes precedence) | `https://sentry.io`  |
+| `SENTRY_URL`       | Alias for `SENTRY_HOST`                               | `https://sentry.io`  |
 
 ## Building
 

docs/src/content/docs/configuration.md

@@ -7,16 +7,22 @@ The Sentry CLI can be configured through environment variables and a local datab
 
 ## Environment Variables
 
-### `SENTRY_URL`
+### `SENTRY_HOST`
 
 Base URL of your Sentry instance. **Only needed for [self-hosted Sentry](./self-hosted/).** SaaS users (sentry.io) should not set this.
 
 ```bash
-export SENTRY_URL=https://sentry.example.com
+export SENTRY_HOST=https://sentry.example.com
 ```
 
 When set, all API requests (including OAuth login) are directed to this URL instead of `https://sentry.io`. 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.
+
+### `SENTRY_URL`
+
+Alias for `SENTRY_HOST`. If both are set, `SENTRY_HOST` takes precedence.
+
 ### `SENTRY_ORG`
 
 Default organization slug. Skips organization auto-detection.

docs/src/content/docs/self-hosted.md

@@ -3,10 +3,10 @@ title: Self-Hosted Sentry
 description: Using the Sentry CLI with a self-hosted Sentry instance
 ---
 
-The CLI works with self-hosted Sentry instances. Set the `SENTRY_URL` environment variable to point at your instance:
+The CLI works with self-hosted Sentry instances. Set the `SENTRY_HOST` (or `SENTRY_URL`) environment variable to point at your instance:
 
 ```bash
-export SENTRY_URL=https://sentry.example.com
+export SENTRY_HOST=https://sentry.example.com
 ```
 
 ## Authenticating
@@ -27,14 +27,14 @@ The OAuth device flow requires **Sentry 26.1.0 or later** and a public OAuth app
 Pass your instance URL and the client ID:
 
 ```bash
-SENTRY_URL=https://sentry.example.com SENTRY_CLIENT_ID=your-client-id sentry auth login
+SENTRY_HOST=https://sentry.example.com SENTRY_CLIENT_ID=your-client-id sentry auth login
 ```
 
 :::tip
 You can export both variables in your shell profile so every CLI invocation picks them up:
 
 ```bash
-export SENTRY_URL=https://sentry.example.com
+export SENTRY_HOST=https://sentry.example.com
 export SENTRY_CLIENT_ID=your-client-id
 ```
 :::
@@ -48,7 +48,7 @@ If your instance is on an older version or you prefer not to create an OAuth app
 3. Pass it to the CLI:
 
 ```bash
-SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
+SENTRY_HOST=https://sentry.example.com sentry auth login --token YOUR_TOKEN
 ```
 
 ## After Login
@@ -66,7 +66,8 @@ If you pass a self-hosted Sentry URL as a command argument (e.g., an issue or ev
 
 | Variable | Description |
 |----------|-------------|
-| `SENTRY_URL` | Base URL of your Sentry instance |
+| `SENTRY_HOST` | Base URL of your Sentry instance (takes precedence over `SENTRY_URL`) |
+| `SENTRY_URL` | Alias for `SENTRY_HOST` |
 | `SENTRY_CLIENT_ID` | Client ID of your public OAuth application |
 | `SENTRY_ORG` | Default organization slug |
 | `SENTRY_PROJECT` | Default project slug (supports `org/project` format) |

src/lib/constants.ts

@@ -11,6 +11,14 @@ export const DEFAULT_SENTRY_HOST = "sentry.io";
 /** Default Sentry SaaS URL (control silo for OAuth and region discovery) */
 export const DEFAULT_SENTRY_URL = `https://${DEFAULT_SENTRY_HOST}`;
 
+/**
+ * Resolve the Sentry instance URL from environment variables.
+ * Checks SENTRY_HOST first, then SENTRY_URL, then falls back to undefined.
+ */
+export function getConfiguredSentryUrl(): string | undefined {
+  return process.env.SENTRY_HOST || process.env.SENTRY_URL || undefined;
+}
+
 /** CLI version string, available for help output and other uses */
 export const CLI_VERSION =
   typeof SENTRY_CLI_VERSION !== "undefined" ? SENTRY_CLI_VERSION : "0.0.0-dev";

src/lib/dsn/code-scanner.ts

@@ -19,7 +19,7 @@ import path from "node:path";
 import * as Sentry from "@sentry/bun";
 import ignore, { type Ignore } from "ignore";
 import pLimit from "p-limit";
-import { DEFAULT_SENTRY_HOST } from "../constants.js";
+import { DEFAULT_SENTRY_HOST, getConfiguredSentryUrl } from "../constants.js";
 import { ConfigError } from "../errors.js";
 import { logger } from "../logger.js";
 import { withTracingSpan } from "../telemetry.js";
@@ -316,18 +316,18 @@ function isCommentedLine(trimmedLine: string): boolean {
  * @returns The expected host domain for DSN validation
  */
 function getExpectedHost(): string {
-  const sentryUrl = process.env.SENTRY_URL;
+  const sentryUrl = getConfiguredSentryUrl();
 
   if (sentryUrl) {
     // Self-hosted: only accept DSNs matching the configured host
     try {
       const url = new URL(sentryUrl);
       return url.host;
     } catch {
-      // Invalid SENTRY_URL - throw immediately since nothing will work
+      // Invalid SENTRY_HOST/SENTRY_URL - throw immediately since nothing will work
       throw new ConfigError(
-        `SENTRY_URL "${sentryUrl}" is not a valid URL`,
-        "Set SENTRY_URL to a valid URL (e.g., https://sentry.example.com) or unset it to use sentry.io"
+        `SENTRY_HOST/SENTRY_URL "${sentryUrl}" is not a valid URL`,
+        "Set SENTRY_HOST/SENTRY_URL to a valid URL (e.g., https://sentry.example.com) or unset it to use sentry.io"
       );
     }
   }

src/lib/oauth.ts

@@ -11,6 +11,7 @@ import {
   TokenErrorResponseSchema,
   TokenResponseSchema,
 } from "../types/index.js";
+import { DEFAULT_SENTRY_URL, getConfiguredSentryUrl } from "./constants.js";
 import { setAuthToken } from "./db/auth.js";
 import { ApiError, AuthError, ConfigError, DeviceFlowError } from "./errors.js";
 import { withHttpSpan } from "./telemetry.js";
@@ -23,7 +24,7 @@ import { withHttpSpan } from "./telemetry.js";
  * by the device flow and token refresh.
  */
 function getSentryUrl(): string {
-  return process.env.SENTRY_URL ?? "https://sentry.io";
+  return getConfiguredSentryUrl() ?? DEFAULT_SENTRY_URL;
 }
 
 /**

src/lib/region.ts

@@ -6,6 +6,7 @@
  */
 
 import { retrieveAnOrganization } from "@sentry/api";
+import { getConfiguredSentryUrl } from "./constants.js";
 import { getOrgByNumericId, getOrgRegion, setOrgRegion } from "./db/regions.js";
 import { stripDsnOrgPrefix } from "./dsn/index.js";
 import { withAuthGuard } from "./errors.js";
@@ -66,8 +67,8 @@ export async function resolveOrgRegion(orgSlug: string): Promise<string> {
  * Returns false for self-hosted instances that don't have regional URLs.
  */
 export function isMultiRegionEnabled(): boolean {
-  // Self-hosted instances (custom SENTRY_URL) typically don't have multi-region
-  const baseUrl = process.env.SENTRY_URL;
+  // Self-hosted instances (custom SENTRY_HOST/SENTRY_URL) typically don't have multi-region
+  const baseUrl = getConfiguredSentryUrl();
   if (baseUrl && !isSentrySaasUrl(baseUrl)) {
     return false;
   }

src/lib/sentry-client.ts

@@ -8,7 +8,11 @@
  * through the SDK function options (baseUrl, fetch, headers).
  */
 
-import { DEFAULT_SENTRY_URL, getUserAgent } from "./constants.js";
+import {
+  DEFAULT_SENTRY_URL,
+  getConfiguredSentryUrl,
+  getUserAgent,
+} from "./constants.js";
 import { getAuthToken, isEnvTokenActive, refreshToken } from "./db/auth.js";
 import { getCachedResponse, storeCachedResponse } from "./response-cache.js";
 import { withHttpSpan } from "./telemetry.js";
@@ -391,7 +395,7 @@ function getAuthenticatedFetch(): typeof fetch {
  * Supports self-hosted instances via SENTRY_URL env var.
  */
 export function getApiBaseUrl(): string {
-  return process.env.SENTRY_URL || DEFAULT_SENTRY_URL;
+  return getConfiguredSentryUrl() ?? DEFAULT_SENTRY_URL;
 }
 
 /**
@@ -402,7 +406,7 @@ export function getApiBaseUrl(): string {
  * (e.g., from URL argument parsing for self-hosted instances) is respected.
  */
 export function getControlSiloUrl(): string {
-  return process.env.SENTRY_URL || DEFAULT_SENTRY_URL;
+  return getConfiguredSentryUrl() ?? DEFAULT_SENTRY_URL;
 }
 
 /**

src/lib/sentry-url-parser.ts

@@ -191,10 +191,13 @@ export function parseSentryUrl(input: string): ParsedSentryUrl | null {
 export function applySentryUrlContext(baseUrl: string): void {
   if (isSentrySaasUrl(baseUrl)) {
     // Clear any self-hosted URL so API calls fall back to default SaaS routing.
-    // Without this, a stale SENTRY_URL would route SaaS requests to the wrong host.
+    // Without this, a stale SENTRY_HOST/SENTRY_URL would route SaaS requests to the wrong host.
+    // biome-ignore lint/performance/noDelete: process.env requires delete to truly unset; assignment coerces to string in Node.js
+    delete process.env.SENTRY_HOST;
     // biome-ignore lint/performance/noDelete: process.env requires delete to truly unset; assignment coerces to string in Node.js
     delete process.env.SENTRY_URL;
     return;
   }
+  process.env.SENTRY_HOST = baseUrl;
   process.env.SENTRY_URL = baseUrl;
 }

src/lib/sentry-urls.ts

@@ -5,14 +5,18 @@
  * Supports self-hosted instances via SENTRY_URL environment variable.
  */
 
-import { DEFAULT_SENTRY_HOST, DEFAULT_SENTRY_URL } from "./constants.js";
+import {
+  DEFAULT_SENTRY_HOST,
+  DEFAULT_SENTRY_URL,
+  getConfiguredSentryUrl,
+} from "./constants.js";
 
 /**
  * Get the Sentry web base URL.
  * Supports self-hosted instances via SENTRY_URL env var.
  */
 export function getSentryBaseUrl(): string {
-  return process.env.SENTRY_URL ?? DEFAULT_SENTRY_URL;
+  return getConfiguredSentryUrl() ?? DEFAULT_SENTRY_URL;
 }
 
 /**