feat(seer): prompt to start free trial on budget/enablement errors

When `issue explain` or `issue plan` fails with a 402 (no budget) or
403 (not enabled) error in an interactive terminal, the CLI now checks
if the org has an available Seer product trial. If one exists, it
prompts the user to start a free trial and retries the command on
success.

The flow mirrors the existing `executeWithAutoAuth` pattern: a new
`executeWithSeerTrialPrompt` middleware wraps `runCommand` and catches
`SeerError`. Errors that aren't trial-eligible (`ai_disabled`, missing
org slug, non-TTY) pass through unchanged.

Key behaviors:
- Checks `GET /customers/{org}/` for unstarted seerUsers trial
  (falls back to seerAutofix for legacy orgs)
- Starts trial via `PUT /customers/{org}/product-trial/`
- API failures during trial check degrade gracefully (show original error)
- consola prompt cancel handled with strict equality check

Author: BYK

AGENTS.md

@@ -645,9 +645,6 @@ mock.module("./some-module", () => ({
 
 ### Decision
 
-<!-- lore:019cc2ef-9be5-722d-bc9f-b07a8197eeed -->
-* **All view subcommands should use \<target> \<id> positional pattern**: All \`\* view\` subcommands should follow a consistent \`\<target> \<id>\` positional argument pattern where target is the optional \`org/project\` specifier. During migration, use opportunistic argument swapping with a stderr warning when args are in wrong order. This is an instance of the broader CLI UX auto-correction pattern: safe when input is already invalid, correction is unambiguous, warning goes to stderr. Normalize at command level, keep parsers pure. Model after \`gh\` CLI conventions.
-
 <!-- lore:019c99d5-69f2-74eb-8c86-411f8512801d -->
 * **Raw markdown output for non-interactive terminals, rendered for TTY**: Markdown-first output pipeline: custom renderer in \`src/lib/formatters/markdown.ts\` walks \`marked\` tokens to produce ANSI-styled output. Commands build CommonMark using helpers (\`mdKvTable()\`, \`mdRow()\`, \`colorTag()\`, \`escapeMarkdownCell()\`, \`safeCodeSpan()\`) and pass through \`renderMarkdown()\`. \`isPlainOutput()\` precedence: \`SENTRY\_PLAIN\_OUTPUT\` > \`NO\_COLOR\` > \`FORCE\_COLOR\` > \`!isTTY\`. \`--json\` always outputs JSON. Colors defined in \`COLORS\` object in \`colors.ts\`. Tests run non-TTY so assertions match raw CommonMark; use \`stripAnsi()\` helper for rendered-mode assertions.
 
@@ -689,7 +686,7 @@ mock.module("./some-module", () => ({
 * **Org-scoped SDK calls follow getOrgSdkConfig + unwrapResult pattern**: All org-scoped API calls in src/lib/api-client.ts: (1) call \`getOrgSdkConfig(orgSlug)\` for regional URL + SDK config, (2) spread into SDK function: \`{ ...config, path: { organization\_id\_or\_slug: orgSlug, ... } }\`, (3) pass to \`unwrapResult(result, errorContext)\`. Shared helpers \`resolveAllTargets\`/\`resolveOrgAndProject\` must NOT call \`fetchProjectId\` — commands that need it enrich targets themselves.
 
 <!-- lore:5ac4e219-ea1f-41cb-8e97-7e946f5848c0 -->
-* **PR workflow: wait for Seer and Cursor BugBot before resolving**: After pushing a PR in the getsentry/cli repo, the CI pipeline includes Seer Code Review and Cursor Bugbot as advisory checks. Both typically take 2-3 minutes but may not trigger on draft PRs — only ready-for-review PRs reliably get bot reviews. The workflow is: push → wait for all CI (including npm build jobs which test the actual bundle) → check for inline review comments from Seer/BugBot → fix if needed → repeat. Use \`gh pr checks \<PR> --watch\` to monitor. Review comments are fetched via \`gh api repos/OWNER/REPO/pulls/NUM/comments\` and \`gh api repos/OWNER/REPO/pulls/NUM/reviews\`.
+* **PR workflow: wait for Seer and Cursor BugBot before resolving**: After pushing a PR in getsentry/cli, CI includes Seer Code Review and Cursor Bugbot as advisory checks (~2-3 min). They may not trigger on draft PRs — use \`gh pr ready\` first. Workflow: push → \`gh pr checks \<PR> --watch\` → check for bot review comments → fix → repeat. Use GraphQL \`reviewThreads\` query with \`isResolved\` filter to find unresolved comments. Reply to bot comments after fixing.
 
 <!-- lore:019cb162-d3ad-7b05-ab4f-f87892d517a6 -->
 * **Shared pagination infrastructure: buildPaginationContextKey and parseCursorFlag**: List commands with cursor pagination use \`buildPaginationContextKey(type, identifier, flags)\` for composite context keys and \`parseCursorFlag(value)\` accepting \`"last"\` magic value. Critical: \`resolveCursor()\` must be called inside the \`org-all\` override closure, not before \`dispatchOrgScopedList\` — otherwise cursor validation errors fire before the correct mode-specific error.

src/bin.ts

@@ -2,10 +2,16 @@ import { isatty } from "node:tty";
 import { run } from "@stricli/core";
 import { app } from "./app.js";
 import { buildContext } from "./context.js";
-import { AuthError, formatError, getExitCode } from "./lib/errors.js";
+import {
+  AuthError,
+  formatError,
+  getExitCode,
+  SeerError,
+} from "./lib/errors.js";
 import { error } from "./lib/formatters/colors.js";
 import { runInteractiveLogin } from "./lib/interactive-login.js";
 import { getEnvLogLevel, setLogLevel } from "./lib/logger.js";
+import { isTrialEligible, promptAndStartTrial } from "./lib/seer-trial.js";
 import { withTelemetry } from "./lib/telemetry.js";
 import { startCleanupOldBinary } from "./lib/upgrade.js";
 import {
@@ -36,6 +42,45 @@ async function runCommand(args: string[]): Promise<void> {
   );
 }
 
+/**
+ * Execute command with automatic Seer trial prompt.
+ *
+ * If the command fails with a trial-eligible SeerError in an interactive TTY,
+ * checks for available trial, prompts user, starts trial, and retries.
+ *
+ * Shows a brief context message (not the full error format with URLs) before
+ * the trial prompt. If the trial isn't available or the user declines, the
+ * full error is re-thrown so the outer handler in main() displays it normally.
+ *
+ * @throws Re-throws the original error when trial is unavailable or declined
+ */
+async function executeWithSeerTrialPrompt(args: string[]): Promise<void> {
+  try {
+    await runCommand(args);
+  } catch (err) {
+    if (err instanceof SeerError && isTrialEligible(err)) {
+      // isTrialEligible ensures orgSlug is defined
+      const started = await promptAndStartTrial(
+        // biome-ignore lint/style/noNonNullAssertion: isTrialEligible guarantees orgSlug is defined
+        err.orgSlug!,
+        err.reason,
+        process.stderr
+      );
+
+      if (started) {
+        process.stderr.write("\nRetrying command...\n\n");
+        await runCommand(args);
+        return;
+      }
+
+      // Trial not started (unavailable, declined, or failed) — re-throw
+      // so the outer error handler in main() displays the full error
+      // with the upgrade/settings URL
+    }
+    throw err;
+  }
+}
+
 /**
  * Execute command with automatic authentication.
  *
@@ -46,7 +91,7 @@ async function runCommand(args: string[]): Promise<void> {
  */
 async function executeWithAutoAuth(args: string[]): Promise<void> {
   try {
-    await runCommand(args);
+    await executeWithSeerTrialPrompt(args);
   } catch (err) {
     // Auto-login for auth errors in interactive TTY environments
     // Use isatty(0) for reliable stdin TTY detection (process.stdin.isTTY can be undefined in Bun)
@@ -71,7 +116,7 @@ async function executeWithAutoAuth(args: string[]): Promise<void> {
 
       if (loginSuccess) {
         process.stderr.write("\nRetrying command...\n\n");
-        await runCommand(args);
+        await executeWithSeerTrialPrompt(args);
         return;
       }
 

src/lib/api-client.ts

@@ -36,9 +36,12 @@ import * as Sentry from "@sentry/bun";
 import type { z } from "zod";
 
 import {
+  type CustomerTrialInfo,
+  CustomerTrialInfoSchema,
   DetailedLogsResponseSchema,
   type DetailedSentryLog,
   LogsResponseSchema,
+  type ProductTrial,
   type ProjectKey,
   type Region,
   type SentryEvent,
@@ -1689,6 +1692,61 @@ export async function triggerSolutionPlanning(
   return data;
 }
 
+// Seer Trial functions
+
+/**
+ * Check if a Seer product trial is available for the organization.
+ *
+ * Fetches customer data from the internal `/customers/{org}/` endpoint and
+ * looks for an unstarted `seerUsers` trial. Returns the trial object if
+ * available, or null if no trial exists or it's already started.
+ *
+ * @param orgSlug - Organization slug
+ * @returns The unstarted trial if available, null otherwise
+ */
+export async function getSeerTrialStatus(
+  orgSlug: string
+): Promise<ProductTrial | null> {
+  const regionUrl = await resolveOrgRegion(orgSlug);
+  const { data } = await apiRequestToRegion<CustomerTrialInfo>(
+    regionUrl,
+    `/customers/${orgSlug}/`,
+    { schema: CustomerTrialInfoSchema }
+  );
+  const trials = data.productTrials ?? [];
+  // Prefer seat-based seerUsers, fall back to legacy seerAutofix
+  return (
+    trials.find((t) => t.category === "seerUsers" && !t.isStarted) ??
+    trials.find((t) => t.category === "seerAutofix" && !t.isStarted) ??
+    null
+  );
+}
+
+/**
+ * Start a Seer product trial for the organization.
+ *
+ * Sends a PUT to the internal `/customers/{org}/product-trial/` endpoint
+ * to activate a 14-day Seer trial. Any org member with `org:read` or higher
+ * permission can start a trial.
+ *
+ * @param orgSlug - Organization slug
+ * @param category - Trial category from getSeerTrialStatus (e.g., "seerUsers", "seerAutofix")
+ * @throws {ApiError} On API errors (e.g., trial already active, permissions)
+ */
+export async function startSeerTrial(
+  orgSlug: string,
+  category: string
+): Promise<void> {
+  const regionUrl = await resolveOrgRegion(orgSlug);
+  await apiRequestToRegion(regionUrl, `/customers/${orgSlug}/product-trial/`, {
+    method: "PUT",
+    body: {
+      referrer: "sentry-cli",
+      productTrial: { category, reasonCode: 0 },
+    },
+  });
+}
+
 // User functions
 
 /**

src/lib/seer-trial.ts

@@ -0,0 +1,112 @@
+/**
+ * Seer Trial Prompt
+ *
+ * Interactive flow to check for and start a Seer product trial
+ * when a Seer command fails due to budget/enablement errors.
+ *
+ * Called from bin.ts when a SeerError is caught. Checks trial availability
+ * via the customer API, prompts the user for confirmation, and starts the
+ * trial if accepted. All failures degrade gracefully — the original error
+ * is re-thrown by the caller if this function returns false.
+ */
+
+import { isatty } from "node:tty";
+
+import { getSeerTrialStatus, startSeerTrial } from "./api-client.js";
+import type { SeerError, SeerErrorReason } from "./errors.js";
+import { success } from "./formatters/colors.js";
+import { logger } from "./logger.js";
+
+/** Seer error reasons eligible for trial prompt */
+const TRIAL_ELIGIBLE_REASONS: ReadonlySet<SeerErrorReason> = new Set([
+  "no_budget",
+  "not_enabled",
+]);
+
+/** User-facing context messages shown before the trial prompt */
+const REASON_CONTEXT: Record<string, string> = {
+  no_budget: "Your organization has run out of Seer quota.",
+  not_enabled: "Seer is not enabled for your organization.",
+};
+
+/**
+ * Check whether a SeerError is eligible for a trial prompt.
+ *
+ * Only `no_budget` and `not_enabled` are eligible — `ai_disabled` is
+ * an explicit admin decision that a trial wouldn't override.
+ * Requires orgSlug (needed for API calls) and interactive terminal.
+ *
+ * @param error - The SeerError to check
+ * @returns true if the error is eligible for a trial prompt
+ */
+export function isTrialEligible(error: SeerError): boolean {
+  return (
+    TRIAL_ELIGIBLE_REASONS.has(error.reason) &&
+    error.orgSlug !== undefined &&
+    isatty(0)
+  );
+}
+
+/**
+ * Attempt to offer and start a Seer trial.
+ *
+ * Flow:
+ * 1. Check trial availability via API (graceful failure → return false)
+ * 2. Show context message + prompt user for confirmation
+ * 3. Start the trial via API
+ *
+ * @param orgSlug - Organization slug
+ * @param reason - The SeerError reason (for context message)
+ * @param stderr - Stderr stream for messages
+ * @returns true if trial was started successfully, false otherwise
+ */
+export async function promptAndStartTrial(
+  orgSlug: string,
+  reason: SeerErrorReason,
+  stderr: NodeJS.WriteStream
+): Promise<boolean> {
+  // 1. Check trial availability (graceful failure → return false)
+  let trial: Awaited<ReturnType<typeof getSeerTrialStatus>>;
+  try {
+    trial = await getSeerTrialStatus(orgSlug);
+  } catch {
+    // Can't check trial status — degrade gracefully
+    return false;
+  }
+
+  if (!trial) {
+    // No trial available — fall through to normal error
+    return false;
+  }
+
+  // 2. Show context and prompt
+  const context = REASON_CONTEXT[reason] ?? "";
+  if (context) {
+    stderr.write(`${context}\n`);
+  }
+
+  const daysText = trial.lengthDays ? `${trial.lengthDays}-day ` : "";
+  const log = logger.withTag("seer");
+  const confirmed = await log.prompt(
+    `A free ${daysText}Seer trial is available. Start trial?`,
+    { type: "confirm", initial: true }
+  );
+
+  // Symbol(clack:cancel) is truthy — strict equality check
+  if (confirmed !== true) {
+    return false;
+  }
+
+  // 3. Start trial using the category from the available trial
+  try {
+    stderr.write("\nStarting Seer trial...\n");
+    await startSeerTrial(orgSlug, trial.category);
+    stderr.write(`${success("✓")} Seer trial activated!\n`);
+    return true;
+  } catch {
+    stderr.write(
+      "Failed to start trial. Please try again or visit your Sentry settings.\n"
+    );
+    return false;
+  }
+}

src/types/index.ts

@@ -49,6 +49,7 @@ export type {
   Breadcrumb,
   BreadcrumbsEntry,
   BrowserContext,
+  CustomerTrialInfo,
   DetailedLogsResponse,
   DetailedSentryLog,
   DeviceContext,
@@ -59,6 +60,7 @@ export type {
   LogsResponse,
   Mechanism,
   OsContext,
+  ProductTrial,
   ProjectKey,
   Region,
   RepositoryProvider,
@@ -83,11 +85,13 @@ export type {
 } from "./sentry.js";
 
 export {
+  CustomerTrialInfoSchema,
   DetailedLogsResponseSchema,
   DetailedSentryLogSchema,
   ISSUE_LEVELS,
   ISSUE_STATUSES,
   LogsResponseSchema,
+  ProductTrialSchema,
   RegionSchema,
   RepositoryProviderSchema,
   SentryLogSchema,

src/types/sentry.ts

@@ -714,3 +714,31 @@ export const SentryTeamSchema = z
   .passthrough();
 
 export type SentryTeam = z.infer<typeof SentryTeamSchema>;
+
+// Product Trials
+
+/** A product trial from the customer endpoint */
+export const ProductTrialSchema = z.object({
+  /** Trial category (e.g., "seerUsers", "seerAutofix") */
+  category: z.string(),
+  /** ISO date when the trial started, null if not started */
+  startDate: z.string().nullable(),
+  /** ISO date when the trial ends, null if not started */
+  endDate: z.string().nullable(),
+  /** Reason code for the trial */
+  reasonCode: z.number(),
+  /** Whether the trial has been activated */
+  isStarted: z.boolean(),
+  /** Duration of the trial in days, null if unknown */
+  lengthDays: z.number().nullable(),
+});
+
+export type ProductTrial = z.infer<typeof ProductTrialSchema>;
+
+/** Subset of customer data needed for trial availability checks */
+export const CustomerTrialInfoSchema = z.object({
+  /** Available and active product trials for the organization */
+  productTrials: z.array(ProductTrialSchema).optional(),
+});
+
+export type CustomerTrialInfo = z.infer<typeof CustomerTrialInfoSchema>;