fix(init): add --app flag and actionable errors for non-interactive monorepo runs (#977)

Running `sentry init --yes --features errors` against a monorepo would
hit the `select-target-app` step, fail to resolve an app
non-interactively, and send `{ cancelled: true }` as resume data to the
server. The server validated it against a schema requiring `selectedApp`
and returned HTTP 500. Users saw:

```
WizardError: HTTP error! status: 500 - {"error":"Invalid resume data: \n- selectedApp: Required"}
```

Three root causes fixed here:

**1. No non-interactive escape hatch.** Added `--app <name>` flag so
CI/agent runs can specify which monorepo app to initialize.
Case-insensitive match against the server-provided app list.

**2. `handleSelect` returned instead of throwing.** When `--yes` was set
with multiple apps, it returned `{ cancelled: true }` which got
forwarded to the server as resume data. It now throws with a formatted
app list and the exact re-run command:

```
This monorepo has 3 apps. Use --app to specify which one to initialize:

  sentry init --yes --features <features> --app web

Available apps:
  web    (Next.js)   /repo/apps/web
  api    (Express)   /repo/apps/api
  admin  (React)     /repo/packages/admin

Or run without --yes to pick interactively:
  sentry init
```

**3. Safety net.** Added a guard in `handleSuspendedStep` that throws
before any `{ cancelled: true }` result can reach `resumeWithRetry`, so
a future regression fails on the CLI side rather than producing an
opaque server error.

Also fixed the `default` branch in `handleInteractive` (same `{
cancelled: true }` bug for unknown prompt kinds) and rewrote
`formatAppList` to iterate over `items` rather than `apps` so the list
stays correct if `payload.options` and `payload.apps` ever arrive at
different lengths.

Closes CLI-17A (77 events, all `is_tty: False` + `flag.yes: True`).

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

plugins/sentry-cli/skills/sentry-cli/references/init.md

@@ -20,6 +20,7 @@ Initialize Sentry in your project (experimental)
 - `-n, --dry-run - Show what would happen without making changes`
 - `--features <value>... - Features to enable: errors,tracing,logs,replay,metrics,profiling,sourcemaps,crons,ai-monitoring,user-feedback`
 - `-t, --team <value> - Team slug to create the project under`
+- `--app <value> - App to initialize in a monorepo (required with --yes when multiple apps are detected)`
 - `--tui - Use the Ink-based interactive UI (default). Pass --no-tui to fall back to plain log output.`
 
 **Examples:**

src/commands/init.ts

@@ -82,6 +82,7 @@ type InitFlags = {
   readonly "dry-run": boolean;
   readonly features?: string[];
   readonly team?: string;
+  readonly app?: string;
   /**
    * Default `true` — Ink is the default UI on both the Bun binary
    * and the npm/Node distribution. Stricli auto-generates a negated
@@ -336,6 +337,13 @@ export const initCommand = buildCommand<
         brief: "Team slug to create the project under",
         optional: true,
       },
+      app: {
+        kind: "parsed",
+        parse: String,
+        brief:
+          "App to initialize in a monorepo (required with --yes when multiple apps are detected)",
+        optional: true,
+      },
       tui: {
         kind: "boolean",
         brief:
@@ -406,6 +414,7 @@ export const initCommand = buildCommand<
         dryRun: flags["dry-run"],
         features: featuresList,
         team: flags.team,
+        app: flags.app,
         org: explicitOrg,
         project: explicitProject,
         // `flags.tui` defaults to `true`. `--no-tui` (auto-generated

src/lib/init/interactive.ts

@@ -11,6 +11,7 @@
  */
 
 import chalk from "chalk";
+import { WizardError } from "../errors.js";
 import {
   abortIfCancelled,
   featureHint,
@@ -50,10 +51,59 @@ export async function handleInteractive(
     case "confirm":
       return await handleConfirm(payload, options, ui);
     default:
-      return { cancelled: true };
+      throw new WizardError(
+        `Unsupported interactive prompt kind: "${(payload as { kind: string }).kind}"`,
+        { rendered: false }
+      );
   }
 }
 
+type AppEntry = { name: string; path: string; framework?: string };
+
+function formatAppList(apps: AppEntry[], items: string[]): string[] {
+  // Name-based lookup keeps this correct even when payload.options and
+  // payload.apps arrive with different lengths.
+  const nameWidth = Math.max(1, ...items.map((n) => n.length));
+  return items.map((name) => {
+    const meta = apps.find((a) => a.name === name);
+    const fw = meta?.framework ? ` (${meta.framework})` : "";
+    const path = meta?.path ? `  ${meta.path}` : "";
+    return `  ${name.padEnd(nameWidth)}${fw}${path}`;
+  });
+}
+
+function buildMultiAppMessage(apps: AppEntry[], items: string[]): string {
+  const exampleApp = items[0] ?? "<app>";
+  return [
+    `This monorepo has ${items.length} apps. Use --app to specify which one to initialize:`,
+    "",
+    `  sentry init --yes --features <features> --app ${exampleApp}`,
+    "",
+    "Available apps:",
+    ...formatAppList(apps, items),
+    "",
+    "Or run without --yes to pick interactively:",
+    "  sentry init",
+  ].join("\n");
+}
+
+function buildAppNotFoundMessage(
+  requested: string,
+  apps: AppEntry[],
+  items: string[]
+): string {
+  const exampleApp = items[0] ?? "<app>";
+  return [
+    `App "${requested}" not found in this monorepo.`,
+    "",
+    "Available apps:",
+    ...formatAppList(apps, items),
+    "",
+    "Re-run with --app <name>, for example:",
+    `  sentry init --yes --features <features> --app ${exampleApp}`,
+  ].join("\n");
+}
+
 async function handleSelect(
   payload: SelectPayload,
   options: InteractiveContext,
@@ -63,24 +113,39 @@ async function handleSelect(
   const items = payload.options ?? apps.map((a) => a.name);
 
   if (items.length === 0) {
-    return { cancelled: true };
+    throw new WizardError("No options available for this selection.", {
+      rendered: false,
+    });
   }
 
-  if (options.yes) {
-    if (items.length === 1) {
-      ui.log.info(`Auto-selected: ${items[0]}`);
-      return { selectedApp: items[0] };
-    }
-    ui.log.error(
-      `--yes requires exactly one option for selection, but found ${items.length}. Run interactively to choose.`
+  if (options.app && payload.apps && payload.apps.length > 0) {
+    const match = items.find(
+      (item) => item.toLowerCase() === options.app?.toLowerCase()
     );
-    return { cancelled: true };
+    if (!match) {
+      const message = buildAppNotFoundMessage(options.app, apps, items);
+      ui.log.error(message);
+      throw new WizardError(message, { rendered: true });
+    }
+    ui.log.info(`Using app: ${match}`);
+    return { selectedApp: match };
+  }
+
+  if (options.yes && items.length === 1) {
+    ui.log.info(`Auto-selected: ${items[0]}`);
+    return { selectedApp: items[0] };
+  }
+
+  if (options.yes && payload.apps && payload.apps.length > 0) {
+    const message = buildMultiAppMessage(apps, items);
+    ui.log.error(message);
+    throw new WizardError(message, { rendered: true });
   }
 
   const selected = await ui.select<string>({
     message: payload.prompt,
-    options: items.map((item, i) => {
-      const app = apps[i];
+    options: items.map((item) => {
+      const app = apps.find((a) => a.name === item);
       return {
         value: item,
         label: item,

src/lib/init/preflight.ts

@@ -99,6 +99,7 @@ function buildResolvedInitContext(
     org,
     team,
     project: selection.project,
+    app: initial.app,
     authToken: getAuthToken(),
     existingProject: selection.existingProject,
   };

src/lib/init/types.ts

@@ -21,6 +21,10 @@ export type WizardOptions = {
   team?: string;
   org?: string;
   project?: string;
+  /** Pre-selected app name for monorepo runs. When set, skips the interactive
+   * app-selection prompt and uses this value directly. Required when `--yes`
+   * is passed against a monorepo with more than one detected app. */
+  app?: string;
   /**
    * Force the non-Ink fallback (`LoggingUI`). Mapped from
    * `--no-tui`. Acts as an escape hatch when the Ink TUI
@@ -44,11 +48,16 @@ export type ResolvedInitContext = {
    */
   team?: string;
   project?: string;
+  /** Pre-selected app name for monorepo runs. Passed through from `--app`. */
+  app?: string;
   authToken?: string;
   existingProject?: ExistingProjectData;
 };
 
-export type InteractiveContext = Pick<ResolvedInitContext, "yes" | "dryRun">;
+export type InteractiveContext = Pick<
+  ResolvedInitContext,
+  "yes" | "dryRun" | "app"
+>;
 
 // Tool suspend payloads
 export type ToolPayload =

src/lib/init/wizard-runner.ts

@@ -227,6 +227,17 @@ async function handleSuspendedStep(
 
     const interactiveResult = await handleInteractive(payload, context, ui);
 
+    // Safety net: { cancelled: true } would send malformed resume data to the
+    // server and produce a cryptic HTTP 500. All interactive handlers should
+    // throw on unresolvable prompts instead of returning this sentinel, but
+    // guard here as well so any future regression fails loudly on the CLI side.
+    if (interactiveResult.cancelled === true) {
+      throw new WizardError(
+        "Setup could not complete: interactive step was not resolved.",
+        { rendered: false }
+      );
+    }
+
     spin.start("Processing...");
     spinState.running = true;