feat(args): parse Sentry web URLs as CLI arguments

Users can now paste Sentry web URLs directly as CLI arguments instead
of manually extracting org/project/issue IDs. Supports both SaaS
(sentry.io) and self-hosted instances.

URL patterns supported:
- /organizations/{org}/issues/{id}/ (issue view/explain/plan)
- /organizations/{org}/issues/{id}/events/{eventId}/ (event view)
- /settings/{org}/projects/{project}/ (project commands)
- /organizations/{org}/traces/{traceId}/ (trace commands)
- /organizations/{org}/ (org-scoped commands)

For self-hosted URLs, automatically sets SENTRY_URL so that API calls,
OAuth device flow, and token refresh target the correct instance.

Also fixes frozen module-level constants in oauth.ts and sentry-client.ts
that captured SENTRY_URL at import time, preventing dynamic URL detection
from working.

Author: BYK

src/commands/event/view.ts

@@ -19,6 +19,10 @@ import {
   resolveOrgAndProject,
   resolveProjectBySlug,
 } from "../../lib/resolve-target.js";
+import {
+  applySentryUrlContext,
+  parseSentryUrl,
+} from "../../lib/sentry-url-parser.js";
 import { buildEventSearchUrl } from "../../lib/sentry-urls.js";
 import { getSpanTreeLines } from "../../lib/span-tree.js";
 import type { SentryEvent, Writer } from "../../types/index.js";
@@ -64,7 +68,16 @@ const USAGE_HINT = "sentry event view <org>/<project> <event-id>";
 
 /**
  * Parse positional arguments for event view.
- * Handles: `<event-id>` or `<target> <event-id>`
+ *
+ * Handles:
+ * - `<event-id>` — event ID only (auto-detect org/project)
+ * - `<target> <event-id>` — explicit target + event ID
+ * - `<sentry-url>` — extract eventId and org from a Sentry event URL
+ *   (e.g., `https://sentry.example.com/organizations/my-org/issues/123/events/abc/`)
+ *
+ * For event URLs, the org is extracted and passed as `targetArg` so the
+ * downstream resolution logic can use it. The URL must contain an eventId
+ * segment — issue-only URLs are not valid for event view.
  *
  * @returns Parsed event ID and optional target arg
  */
@@ -81,6 +94,21 @@ export function parsePositionalArgs(args: string[]): {
     throw new ContextError("Event ID", USAGE_HINT);
   }
 
+  // URL detection — extract eventId and org from Sentry event URLs
+  const urlParsed = parseSentryUrl(first);
+  if (urlParsed) {
+    applySentryUrlContext(urlParsed.baseUrl);
+    if (urlParsed.eventId) {
+      // Event URL: use org as target, eventId from the URL
+      return { eventId: urlParsed.eventId, targetArg: `${urlParsed.org}/` };
+    }
+    // URL recognized but no eventId — not valid for event view
+    throw new ContextError(
+      "Event ID in URL (use a URL like /issues/{id}/events/{eventId}/)",
+      USAGE_HINT
+    );
+  }
+
   if (args.length === 1) {
     // Single arg - must be event ID
     return { eventId: first, targetArg: undefined };

src/lib/arg-parsing.ts

@@ -6,6 +6,8 @@
  * project list) and single-item commands (issue view, explain, plan).
  */
 
+import type { ParsedSentryUrl } from "./sentry-url-parser.js";
+import { applySentryUrlContext, parseSentryUrl } from "./sentry-url-parser.js";
 import { isAllDigits } from "./utils.js";
 
 /** Default span depth when no value is provided */
@@ -96,11 +98,60 @@ export type ParsedOrgProject =
   | { type: typeof ProjectSpecificationType.ProjectSearch; projectSlug: string }
   | { type: typeof ProjectSpecificationType.AutoDetect };
 
+/**
+ * Map a parsed Sentry URL to a ParsedOrgProject.
+ * If the URL contains a project slug, returns explicit; otherwise org-all.
+ */
+function orgProjectFromUrl(parsed: ParsedSentryUrl): ParsedOrgProject {
+  if (parsed.project) {
+    return { type: "explicit", org: parsed.org, project: parsed.project };
+  }
+  return { type: "org-all", org: parsed.org };
+}
+
+/**
+ * Map a parsed Sentry URL to a ParsedIssueArg.
+ * Handles numeric group IDs and short IDs (e.g., "CLI-G") from the URL path.
+ */
+function issueArgFromUrl(parsed: ParsedSentryUrl): ParsedIssueArg | null {
+  const { issueId } = parsed;
+  if (!issueId) {
+    return null;
+  }
+
+  // Numeric group ID (e.g., /issues/32886/)
+  if (isAllDigits(issueId)) {
+    return {
+      type: "explicit-org-numeric",
+      org: parsed.org,
+      numericId: issueId,
+    };
+  }
+
+  // Short ID with dash (e.g., /issues/CLI-G/ or /issues/SPOTLIGHT-ELECTRON-4Y/)
+  const dashIdx = issueId.lastIndexOf("-");
+  if (dashIdx > 0) {
+    const project = issueId.slice(0, dashIdx);
+    const suffix = issueId.slice(dashIdx + 1).toUpperCase();
+    if (project && suffix) {
+      return { type: "explicit", org: parsed.org, project, suffix };
+    }
+  }
+
+  // No dash — treat as suffix-only with org context
+  return {
+    type: "explicit-org-suffix",
+    org: parsed.org,
+    suffix: issueId.toUpperCase(),
+  };
+}
+
 /**
  * Parse an org/project positional argument string.
  *
  * Supports the following patterns:
  * - `undefined` or empty → auto-detect from DSN/config
+ * - `https://sentry.io/organizations/org/...` → extract from Sentry URL
  * - `sentry/cli` → explicit org and project
  * - `sentry/` → org with all projects
  * - `/cli` → search for project across all orgs (leading slash)
@@ -123,6 +174,13 @@ export function parseOrgProjectArg(arg: string | undefined): ParsedOrgProject {
 
   const trimmed = arg.trim();
 
+  // URL detection — extract org/project from Sentry web URLs
+  const urlParsed = parseSentryUrl(trimmed);
+  if (urlParsed) {
+    applySentryUrlContext(urlParsed.baseUrl);
+    return orgProjectFromUrl(urlParsed);
+  }
+
   if (trimmed.includes("/")) {
     const slashIndex = trimmed.indexOf("/");
     const org = trimmed.slice(0, slashIndex);
@@ -287,6 +345,18 @@ function parseWithDash(arg: string): ParsedIssueArg {
 }
 
 export function parseIssueArg(arg: string): ParsedIssueArg {
+  // 0. URL detection — extract issue ID from Sentry web URLs
+  const urlParsed = parseSentryUrl(arg);
+  if (urlParsed) {
+    applySentryUrlContext(urlParsed.baseUrl);
+    const result = issueArgFromUrl(urlParsed);
+    if (result) {
+      return result;
+    }
+    // URL recognized but no issue ID — fall through to normal parsing
+    // (shouldn't happen for issue commands, but defensive)
+  }
+
   // 1. Pure numeric → direct fetch by ID
   if (isAllDigits(arg)) {
     return { type: "numeric", id: arg };

src/lib/oauth.ts

@@ -15,8 +15,16 @@ import { setAuthToken } from "./db/auth.js";
 import { ApiError, AuthError, ConfigError, DeviceFlowError } from "./errors.js";
 import { withHttpSpan } from "./telemetry.js";
 
-// Sentry instance URL (supports self-hosted via env override)
-const SENTRY_URL = process.env.SENTRY_URL ?? "https://sentry.io";
+/**
+ * Get the Sentry instance URL for OAuth endpoints.
+ *
+ * Read lazily (not at module load) so that SENTRY_URL set after import
+ * (e.g., from URL argument parsing for self-hosted instances) is respected
+ * by the device flow and token refresh.
+ */
+function getSentryUrl(): string {
+  return process.env.SENTRY_URL ?? "https://sentry.io";
+}
 
 /**
  * OAuth client ID
@@ -82,7 +90,7 @@ async function fetchWithConnectionError(
 
     if (isConnectionError) {
       throw new ApiError(
-        `Cannot connect to Sentry at ${SENTRY_URL}`,
+        `Cannot connect to Sentry at ${getSentryUrl()}`,
         0,
         "Check your network connection and SENTRY_URL configuration"
       );
@@ -103,7 +111,7 @@ function requestDeviceCode() {
 
   return withHttpSpan("POST", "/oauth/device/code/", async () => {
     const response = await fetchWithConnectionError(
-      `${SENTRY_URL}/oauth/device/code/`,
+      `${getSentryUrl()}/oauth/device/code/`,
       {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
@@ -146,7 +154,7 @@ function requestDeviceCode() {
 function pollForToken(deviceCode: string): Promise<TokenResponse> {
   return withHttpSpan("POST", "/oauth/token/", async () => {
     const response = await fetchWithConnectionError(
-      `${SENTRY_URL}/oauth/token/`,
+      `${getSentryUrl()}/oauth/token/`,
       {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
@@ -332,7 +340,7 @@ export function refreshAccessToken(
 
   return withHttpSpan("POST", "/oauth/token/", async () => {
     const response = await fetchWithConnectionError(
-      `${SENTRY_URL}/oauth/token/`,
+      `${getSentryUrl()}/oauth/token/`,
       {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },

src/lib/sentry-client.ts

@@ -12,11 +12,10 @@ import { DEFAULT_SENTRY_URL, getUserAgent } from "./constants.js";
 import { refreshToken } from "./db/auth.js";
 import { withHttpSpan } from "./telemetry.js";
 
-/**
- * Control silo URL - handles OAuth, user accounts, and region routing.
- * This is always sentry.io for SaaS, or the base URL for self-hosted.
- */
-const CONTROL_SILO_URL = process.env.SENTRY_URL || DEFAULT_SENTRY_URL;
+// CONTROL_SILO_URL was previously a module-level const that captured
+// process.env.SENTRY_URL at import time. This broke self-hosted URL
+// detection where SENTRY_URL is set after import. Now read lazily
+// via getControlSiloUrl().
 
 /** Request timeout in milliseconds */
 const REQUEST_TIMEOUT_MS = 30_000;
@@ -291,9 +290,12 @@ export function getApiBaseUrl(): string {
 /**
  * Get the control silo URL.
  * This is always sentry.io for SaaS, or the custom URL for self-hosted.
+ *
+ * Read lazily (not at module load) so that SENTRY_URL set after import
+ * (e.g., from URL argument parsing for self-hosted instances) is respected.
  */
 export function getControlSiloUrl(): string {
-  return CONTROL_SILO_URL;
+  return process.env.SENTRY_URL || DEFAULT_SENTRY_URL;
 }
 
 /**
@@ -339,7 +341,7 @@ export function getDefaultSdkConfig() {
  * Used for endpoints that are always on the control silo (OAuth, user accounts, regions).
  */
 export function getControlSdkConfig() {
-  return getSdkConfig(CONTROL_SILO_URL);
+  return getSdkConfig(getControlSiloUrl());
 }
 
 /**

src/lib/sentry-url-parser.ts

@@ -0,0 +1,141 @@
+/**
+ * Sentry URL Parser
+ *
+ * Extracts org, project, issue, event, and trace identifiers from Sentry web URLs.
+ * Supports both SaaS (*.sentry.io) and self-hosted instances.
+ *
+ * For self-hosted URLs, also configures the SENTRY_URL environment variable
+ * so that subsequent API calls reach the correct instance.
+ */
+
+import { isSentrySaasUrl } from "./sentry-urls.js";
+
+/**
+ * Components extracted from a Sentry web URL.
+ *
+ * All fields except `baseUrl` and `org` are optional — presence depends
+ * on which URL pattern was matched.
+ */
+export type ParsedSentryUrl = {
+  /** Scheme + host of the Sentry instance (e.g., "https://sentry.io" or "https://sentry.example.com") */
+  baseUrl: string;
+  /** Organization slug from the URL path */
+  org: string;
+  /** Issue identifier — numeric group ID (e.g., "32886") or short ID (e.g., "CLI-G") */
+  issueId?: string;
+  /** Event ID from /issues/{id}/events/{eventId}/ paths */
+  eventId?: string;
+  /** Project slug from /settings/{org}/projects/{project}/ paths */
+  project?: string;
+  /** Trace ID from /organizations/{org}/traces/{traceId}/ paths */
+  traceId?: string;
+};
+
+/**
+ * Try to match /organizations/{org}/... path patterns.
+ *
+ * @returns Parsed result or null if pattern doesn't match
+ */
+function matchOrganizationsPath(
+  baseUrl: string,
+  segments: string[]
+): ParsedSentryUrl | null {
+  if (segments[0] !== "organizations" || !segments[1]) {
+    return null;
+  }
+
+  const org = segments[1];
+
+  // /organizations/{org}/issues/{id}/ (optionally with /events/{eventId}/)
+  if (segments[2] === "issues" && segments[3]) {
+    const eventId =
+      segments[4] === "events" && segments[5] ? segments[5] : undefined;
+    return { baseUrl, org, issueId: segments[3], eventId };
+  }
+
+  // /organizations/{org}/traces/{traceId}/
+  if (segments[2] === "traces" && segments[3]) {
+    return { baseUrl, org, traceId: segments[3] };
+  }
+
+  // /organizations/{org}/ (org only)
+  return { baseUrl, org };
+}
+
+/**
+ * Try to match /settings/{org}/projects/{project}/ path pattern.
+ *
+ * @returns Parsed result or null if pattern doesn't match
+ */
+function matchSettingsPath(
+  baseUrl: string,
+  segments: string[]
+): ParsedSentryUrl | null {
+  if (
+    segments[0] !== "settings" ||
+    !segments[1] ||
+    segments[2] !== "projects" ||
+    !segments[3]
+  ) {
+    return null;
+  }
+
+  return { baseUrl, org: segments[1], project: segments[3] };
+}
+
+/**
+ * Parse a Sentry web URL and extract its components.
+ *
+ * Recognizes these path patterns (both SaaS and self-hosted):
+ * - `/organizations/{org}/issues/{id}/`
+ * - `/organizations/{org}/issues/{id}/events/{eventId}/`
+ * - `/settings/{org}/projects/{project}/`
+ * - `/organizations/{org}/traces/{traceId}/`
+ * - `/organizations/{org}/`
+ *
+ * @param input - Raw string that may or may not be a URL
+ * @returns Parsed components, or null if input is not a recognized Sentry URL
+ */
+export function parseSentryUrl(input: string): ParsedSentryUrl | null {
+  // Quick reject — must look like a URL
+  if (!(input.startsWith("http://") || input.startsWith("https://"))) {
+    return null;
+  }
+
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    return null;
+  }
+
+  const baseUrl = `${url.protocol}//${url.host}`;
+  const segments = url.pathname.split("/").filter(Boolean);
+
+  return (
+    matchOrganizationsPath(baseUrl, segments) ??
+    matchSettingsPath(baseUrl, segments)
+  );
+}
+
+/**
+ * Configure `SENTRY_URL` for self-hosted instances detected from a parsed URL.
+ *
+ * Only sets the env var when ALL of these conditions are met:
+ * 1. The URL is NOT a Sentry SaaS domain (*.sentry.io) — SaaS uses multi-region routing
+ * 2. `SENTRY_URL` is not already set — respect explicit user configuration
+ *
+ * This ensures that API calls, OAuth device flow, and token refresh all target
+ * the correct self-hosted instance when a user pastes a URL as an argument.
+ *
+ * @param baseUrl - The scheme + host extracted from the URL (e.g., "https://sentry.example.com")
+ */
+export function applySentryUrlContext(baseUrl: string): void {
+  if (isSentrySaasUrl(baseUrl)) {
+    return;
+  }
+  if (process.env.SENTRY_URL) {
+    return;
+  }
+  process.env.SENTRY_URL = baseUrl;
+}