feat(init): add init command for guided Sentry project setup

.gitignore

@@ -1,5 +1,6 @@
 # dependencies (bun install)
 node_modules
+package-lock.json
 
 # output
 out
@@ -36,6 +37,7 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .cache
 *.tsbuildinfo
 .turbo
+.mastra
 
 # docs
 docs/dist

biome.jsonc

@@ -2,7 +2,7 @@
   "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
   "extends": ["ultracite/core"],
   "files": {
-    "includes": ["!docs"]
+    "includes": ["!docs", "!test/init-eval/templates"]
   },
   "javascript": {
     "globals": ["Bun"]

docs/src/content/docs/commands/init.md

@@ -0,0 +1,63 @@
+---
+title: init
+description: AI-powered project setup wizard for the Sentry CLI
+---
+
+Set up Sentry in your project with an AI-powered wizard. The `init` command detects your platform and framework, installs the Sentry SDK, and instruments your code for error monitoring, tracing, and more.
+
+**Prerequisites:** You must be authenticated first. Run `sentry auth login` if you haven't already.
+
+## Usage
+
+```bash
+sentry init [directory]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[directory]` | Project directory (default: current directory) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Continue even if Sentry is already installed |
+| `-y, --yes` | Non-interactive mode (accept defaults) |
+| `--dry-run` | Preview changes without applying them |
+| `--features <list>` | Comma-separated features: `errors`, `tracing`, `logs`, `replay`, `metrics` |
+
+## Examples
+
+```bash
+# Run the wizard in the current directory
+sentry init
+
+# Target a subdirectory
+sentry init ./my-app
+
+# Preview what changes would be made
+sentry init --dry-run
+
+# Select specific features
+sentry init --features errors,tracing,logs
+
+# Non-interactive mode (accept all defaults)
+sentry init --yes
+```
+
+## What the wizard does
+
+1. **Detects your framework** — scans your project files to identify the platform and framework
+2. **Installs the SDK** — adds the appropriate Sentry SDK package to your project
+3. **Instruments your code** — configures error monitoring, tracing, and any selected features
+
+## Supported platforms
+
+The wizard currently supports:
+
+- **JavaScript / TypeScript** — Next.js, Express, SvelteKit, React
+- **Python** — Flask, FastAPI
+
+More platforms and frameworks are coming soon.

docs/src/content/docs/getting-started.mdx

@@ -106,6 +106,7 @@ Credentials are stored in a SQLite database at `~/.sentry/` with restricted file
 
 Once authenticated, you can start using the CLI:
 
+- [Initialize Sentry](../commands/init/) - Set up Sentry in your project with the guided wizard
 - [Organization commands](../commands/org/) - List and view organizations
 - [Project commands](../commands/project/) - Manage projects
 - [Issue commands](../commands/issue/) - Track and manage issues

package.json

@@ -6,7 +6,10 @@
     "url": "git+https://github.com/getsentry/cli.git"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
     "@biomejs/biome": "2.3.8",
+    "@clack/prompts": "^0.11.0",
+    "@mastra/client-js": "^1.4.0",
     "@sentry/api": "^0.21.0",
     "@sentry/bun": "10.39.0",
     "@sentry/esbuild-plugin": "^2.23.0",
@@ -27,6 +30,7 @@
     "http-cache-semantics": "^4.2.0",
     "ignore": "^7.0.5",
     "marked": "^15",
+    "openai": "^6.22.0",
     "p-limit": "^7.2.0",
     "pretty-ms": "^9.3.0",
     "qrcode-terminal": "^0.12.0",
@@ -66,6 +70,7 @@
     "test:unit": "bun test --timeout 15000 test/lib test/commands test/types --coverage --coverage-reporter=lcov",
     "test:isolated": "bun test --timeout 15000 test/isolated",
     "test:e2e": "bun test --timeout 15000 test/e2e",
+    "test:init-eval": "bun test test/init-eval --timeout 600000 --concurrency 6",
     "generate:skill": "bun run script/generate-skill.ts",
     "check:skill": "bun run script/check-skill.ts",
     "check:deps": "bun run script/check-no-deps.ts"

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -630,6 +630,20 @@ View logs associated with a trace
 - `-q, --query <value> - Additional filter query (Sentry search syntax)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
 
+### Init
+
+Initialize Sentry in your project
+
+#### `sentry init <directory>`
+
+Initialize Sentry in your project
+
+**Flags:**
+- `--force - Continue even if Sentry is already installed`
+- `-y, --yes - Non-interactive mode (accept defaults)`
+- `--dry-run - Preview changes without applying them`
+- `--features <value> - Comma-separated features: errors,tracing,logs,replay,metrics`
+
 ### Issues
 
 List issues in a project

src/app.ts

@@ -13,6 +13,7 @@ import { whoamiCommand } from "./commands/auth/whoami.js";
 import { cliRoute } from "./commands/cli/index.js";
 import { eventRoute } from "./commands/event/index.js";
 import { helpCommand } from "./commands/help.js";
+import { initCommand } from "./commands/init.js";
 import { issueRoute } from "./commands/issue/index.js";
 import { listCommand as issueListCommand } from "./commands/issue/list.js";
 import { logRoute } from "./commands/log/index.js";
@@ -64,6 +65,7 @@ export const routes = buildRouteMap({
     event: eventRoute,
     log: logRoute,
     trace: traceRoute,
+    init: initCommand,
     api: apiCommand,
     issues: issueListCommand,
     orgs: orgListCommand,

src/commands/init.ts

@@ -0,0 +1,84 @@
+/**
+ * sentry init
+ *
+ * Initialize Sentry in a project using the remote wizard workflow.
+ * Communicates with the Mastra API via suspend/resume to perform
+ * local filesystem operations and interactive prompts.
+ */
+
+import path from "node:path";
+import type { SentryContext } from "../context.js";
+import { buildCommand } from "../lib/command.js";
+import { runWizard } from "../lib/init/wizard-runner.js";
+
+type InitFlags = {
+  readonly force: boolean;
+  readonly yes: boolean;
+  readonly "dry-run": boolean;
+  readonly features?: string;
+};
+
+export const initCommand = buildCommand<InitFlags, [string?], SentryContext>({
+  docs: {
+    brief: "Initialize Sentry in your project",
+    fullDescription:
+      "Runs the Sentry setup wizard to detect your project's framework, " +
+      "install the SDK, and configure error monitoring. Uses a remote " +
+      "workflow that coordinates local file operations through the CLI.",
+  },
+  parameters: {
+    positional: {
+      kind: "tuple",
+      parameters: [
+        {
+          placeholder: "directory",
+          brief: "Project directory (default: current directory)",
+          parse: String,
+          optional: true,
+        },
+      ],
+    },
+    flags: {
+      force: {
+        kind: "boolean",
+        brief: "Continue even if Sentry is already installed",
+        default: false,
+      },
+      yes: {
+        kind: "boolean",
+        brief: "Non-interactive mode (accept defaults)",
+        default: false,
+      },
+      "dry-run": {
+        kind: "boolean",
+        brief: "Preview changes without applying them",
+        default: false,
+      },
+      features: {
+        kind: "parsed",
+        parse: String,
+        brief: "Comma-separated features: errors,tracing,logs,replay,metrics",
+        optional: true,
+        placeholder: "list",
+      },
+    },
+    aliases: {
+      y: "yes",
+    },
+  },
+  async func(this: SentryContext, flags: InitFlags, directory?: string) {
+    const targetDir = directory ? path.resolve(this.cwd, directory) : this.cwd;
+    const featuresList = flags.features
+      ?.split(",")
+      .map((f) => f.trim())
+      .filter(Boolean);
+
+    await runWizard({
+      directory: targetDir,
+      force: flags.force,
+      yes: flags.yes,
+      dryRun: flags["dry-run"],
+      features: featuresList,
+    });
+  },
+});

src/commands/project/create.ts

@@ -46,6 +46,7 @@ import {
   resolveOrCreateTeam,
 } from "../../lib/resolve-team.js";
 import { buildProjectUrl } from "../../lib/sentry-urls.js";
+import { slugify } from "../../lib/utils.js";
 import type { SentryProject, Writer } from "../../types/index.js";
 
 /** Usage hint template — base command without positionals */
@@ -107,25 +108,6 @@ function normalizePlatform(platform: string, stderr: Writer): string {
   return corrected;
 }
 
-/**
- * Convert a project name to its expected Sentry slug.
- * Aligned with Sentry's canonical implementation:
- * https://github.com/getsentry/sentry/blob/master/static/app/utils/slugify.tsx
- *
- * @example slugify("My Cool App") // "my-cool-app"
- * @example slugify("my-app")      // "my-app"
- * @example slugify("Café Project") // "cafe-project"
- * @example slugify("my_app")      // "my_app"
- */
-function slugify(name: string): string {
-  return name
-    .normalize("NFKD")
-    .toLowerCase()
-    .replace(/[^a-z0-9_\s-]/g, "")
-    .replace(/[-\s]+/g, "-")
-    .replace(/^-|-$/g, "");
-}
-
 /**
  * Check whether an API error is about an invalid platform value.
  * Relies on Sentry's error message wording — may need updating if the API changes.

src/lib/banner.ts

@@ -0,0 +1,39 @@
+/**
+ * Banner Formatting
+ *
+ * Standalone module for the Sentry ASCII banner.
+ * Extracted to avoid circular imports (wizard-runner → help → app → init → wizard-runner).
+ */
+
+import chalk from "chalk";
+
+/** ASCII art banner rows for gradient coloring */
+const BANNER_ROWS = [
+  "  ███████╗███████╗███╗   ██╗████████╗██████╗ ██╗   ██╗",
+  "  ██╔════╝██╔════╝████╗  ██║╚══██╔══╝██╔══██╗╚██╗ ██╔╝",
+  "  ███████╗█████╗  ██╔██╗ ██║   ██║   ██████╔╝ ╚████╔╝ ",
+  "  ╚════██║██╔══╝  ██║╚██╗██║   ██║   ██╔══██╗  ╚██╔╝  ",
+  "  ███████║███████╗██║ ╚████║   ██║   ██║  ██║   ██║   ",
+  "  ╚══════╝╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   ",
+];
+
+/** Purple gradient colors from bright to dark (Sentry brand-inspired) */
+const BANNER_GRADIENT = [
+  "#B4A4DE",
+  "#9C84D4",
+  "#8468C8",
+  "#6C4EBA",
+  "#5538A8",
+  "#432B8A",
+];
+
+/**
+ * Format the banner with a vertical gradient effect.
+ * Each row gets progressively darker purple.
+ */
+export function formatBanner(): string {
+  return BANNER_ROWS.map((row, i) => {
+    const color = BANNER_GRADIENT[i] ?? "#B4A4DE";
+    return chalk.hex(color)(row);
+  }).join("\n");
+}

src/lib/help.ts

@@ -6,43 +6,12 @@
  * Commands are auto-generated from Stricli's route structure.
  */
 
-import chalk from "chalk";
 import { routes } from "../app.js";
 import type { Writer } from "../types/index.js";
+import { formatBanner } from "./banner.js";
 import { isAuthenticated } from "./db/auth.js";
 import { cyan, magenta, muted } from "./formatters/colors.js";
 
-/** ASCII art banner rows for gradient coloring */
-const BANNER_ROWS = [
-  "  ███████╗███████╗███╗   ██╗████████╗██████╗ ██╗   ██╗",
-  "  ██╔════╝██╔════╝████╗  ██║╚══██╔══╝██╔══██╗╚██╗ ██╔╝",
-  "  ███████╗█████╗  ██╔██╗ ██║   ██║   ██████╔╝ ╚████╔╝ ",
-  "  ╚════██║██╔══╝  ██║╚██╗██║   ██║   ██╔══██╗  ╚██╔╝  ",
-  "  ███████║███████╗██║ ╚████║   ██║   ██║  ██║   ██║   ",
-  "  ╚══════╝╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   ",
-];
-
-/** Purple gradient colors from bright to dark (Sentry brand-inspired) */
-const BANNER_GRADIENT = [
-  "#B4A4DE",
-  "#9C84D4",
-  "#8468C8",
-  "#6C4EBA",
-  "#5538A8",
-  "#432B8A",
-];
-
-/**
- * Format the banner with a vertical gradient effect.
- * Each row gets progressively darker purple.
- */
-function formatBanner(): string {
-  return BANNER_ROWS.map((row, i) => {
-    const color = BANNER_GRADIENT[i] ?? "#B4A4DE";
-    return chalk.hex(color)(row);
-  }).join("\n");
-}
-
 const TAGLINE = "The command-line interface for Sentry";
 
 type HelpCommand = {