feat(nextjs): Add --skip-auth flag for headless CLI operation #1183

codyde · 2026-01-08T05:06:42Z

Summary

Adds support for fully headless/automated Sentry setup without browser authentication. This enables CI/CD pipelines and AI agents to scaffold Sentry configuration with environment variable placeholders that can be populated later.

New CLI Flags

Flag	Description
`--skip-auth`	Skip Sentry authentication, use env var placeholders
`--tracing`	Enable performance/tracing monitoring
`--replay`	Enable Session Replay
`--logs`	Enable Sentry Logs
`--tunnel-route`	Enable tunnel route for ad-blocker circumvention
`--mcp-cursor`	Add MCP config for Cursor
`--mcp-vscode`	Add MCP config for VS Code
`--mcp-claude`	Add MCP config for Claude Code
`--mcp-opencode`	Add MCP config for OpenCode
`--mcp-jetbrains`	Show MCP config for JetBrains IDEs

Example Usage

npx @sentry/wizard -i nextjs \
  --skip-auth \
  --tracing \
  --replay \
  --logs \
  --mcp-opencode \
  --ignore-git-changes

Behavior in `--skip-auth` Mode

Config files use process.env.SENTRY_DSN / process.env.NEXT_PUBLIC_SENTRY_DSN
next.config.js uses process.env.SENTRY_ORG and process.env.SENTRY_PROJECT
Creates .env.example documenting all required environment variables
MCP configs use base URL (mcp.sentry.dev/mcp) without project scope
Skips: example page creation, CI setup prompts, turbopack warning
Feature flags default to false (must be explicitly enabled)

Generated `.env.example`

# Sentry Configuration
SENTRY_DSN=
NEXT_PUBLIC_SENTRY_DSN=
SENTRY_ORG=
SENTRY_PROJECT=
SENTRY_AUTH_TOKEN=

Use Cases

AI Agent Setup: Agents can run the wizard headlessly and populate env vars programmatically
CI/CD Scaffolding: Set up Sentry structure in pipelines without interactive prompts
Template Projects: Create project templates with Sentry pre-configured for env vars

Testing

yarn build passes
yarn lint passes
yarn test passes
Manual testing with --skip-auth flag in test Next.js project

Add support for fully headless/automated Sentry setup without browser authentication. This enables CI/CD pipelines and AI agents to scaffold Sentry configuration with environment variable placeholders. New CLI flags: - --skip-auth: Skip authentication, use env var placeholders - --tracing: Enable performance monitoring - --replay: Enable Session Replay - --logs: Enable Sentry Logs - --tunnel-route: Enable tunnel route - --mcp-cursor/vscode/claude/opencode/jetbrains: Add MCP configs In skip-auth mode: - Config files use process.env.SENTRY_DSN / NEXT_PUBLIC_SENTRY_DSN - next.config uses process.env.SENTRY_ORG / SENTRY_PROJECT - Creates .env.example documenting required variables - MCP configs use base URL without project scope - Skips example page, CI setup, and turbopack warning

github-actions · 2026-01-08T05:06:57Z

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

New Features ✨

Cloudflare

Support wrapping workers main file by JPeer264 in #1156
Enable update of the wrangler file by JPeer264 in #1149
Add a basic skeleton for cloudflare by JPeer264 in #1147

Mcp

Add multi-select support for MCP configuration by cursor in #1153
Add OpenCode as MCP server provider option by codyde in #1154

Other

(nextjs) Add --skip-auth flag for headless CLI operation by codyde in #1183

Bug Fixes 🐛

(next) Remove Turbopack outro warning by logaretm in #1173
(react-router) Avoid force-running npx react-router reveal by Lms24 in #1181

Build / dependencies / internal 🔧

Deps

Update tmp from 0.0.33 to 0.2.4 by Lms24 in #1176
Update brace-expansion to 2.0.2 and 1.1.12 by Lms24 in #1175
Bump js-yaml from 4.1.0 to 4.1.1 by dependabot in #1114
Bump vite from 6.3.6 to 6.4.1 in /e2e-tests/test-applications/cloudflare-wrangler-sourcemaps-test-app by dependabot in #1112
Bump devalue from 4.3.3 to 5.6.1 in /e2e-tests/test-applications/cloudflare-wrangler-sourcemaps-test-app by dependabot in #1172

Test

Clean up e2e test utils by Lms24 in #1182
Update vite to 7.3.0 in pnpm-workspace-test-app by Lms24 in #1174
Unstale lock file in pnpm-workspace-test-app by Lms24 in #1170
Update @vitest/coverage-v8 to bump glob to 10.5.0 by Lms24 in #1169
Update @angular/common and related dependencies by Lms24 in #1168
Update @cloudflare/vitest-pool-workers dependencies by Lms24 in #1167

Other

(publish) Use fully automatic changelog generation by Lms24 in #1138
Remove duplications for SDKs that do not support spotlight by JPeer264 in #1151
Wrong changelog category for last update by JPeer264 in #1150

Other

test(e2e): Migrate React-native and Expo e2e tests to use clifty by Lms24 in #1179
test(e2e): Migrate Flutter e2e tests to use clifty by Lms24 in #1180
test(e2e): Migrate Nuxt e2e tests to use clifty by Lms24 in #1178
test(e2e): Migrate Angular e2e tests to clifty by Lms24 in #1165

_{🤖 This preview updates automatically when you update the PR.}

Lms24

Thanks for opening this PR! I think adding a non-blocking execution flow makes sense. Both for agents as well as humans :) However, I would ask that we take one of these two routes but not mix things up:

We add a --agentMode CLI flag which fully automates every step to make it non-blocking. It can work in conjuction with other high-level CLI flags like --tracing for high-level options but it can be used to skip over multiple steps or change wizard behaviour however otherwise necessary
We add specific flags for each step. For example --auth=false (or --skip-auth) controls authentication and the related code injection steps requiring dsns, project/org data etc (like right now). But in addition, --example-page=false skips the example page, --tunnelRoute decides whether to set tunnelRoute, --setup-ci for (not) skipping CI setup, etc.

I would personally prefer 2 because this allows to make the wizard non-blocking for non-agentic use, too. For example, we could use it in docs to customize the wizard code snippet more based on the selected features on the setup page. Same in the in-product onboarding.

I just want to avoid that a flag like --skip-auth does more than its name implies.
Likewise, I'd slightly prefer "enable" naming over "skip". So users set --example-page=false instead of --skip-example-page. This more resembles the default behaviour of the wizard in the interactive mode. Though happy to hear counter arguments here :)

WDYT?

Lms24 · 2026-01-08T10:44:03Z

src/nextjs/nextjs-wizard.ts

+
+  // Determine tunnel route setting
+  let tunnelRoute: boolean;
+  if (skipAuth) {


m: is there a reason we only apply the --tunnelRoute argument on if --skip-auth is set? I'd tend towards treating these flags independently of each other

Lms24 · 2026-01-08T10:48:22Z

src/nextjs/nextjs-wizard.ts

+  let shouldCreateExamplePage = false;
+  if (!skipAuth) {
+    shouldCreateExamplePage = await askShouldCreateExamplePage();


m: I'd rather have this be its own flag. Nothing about --skip-auth suggests that it skips example page creation.

Instead, I suggest we do something like this:

const shouldCreateExamplePage = options.examplePage ?? await askShouldCreateExamplePage();

Lms24 · 2026-01-08T10:50:02Z

src/nextjs/nextjs-wizard.ts

+  // Skip turbopack warning in skip-auth mode
+  if (!skipAuth) {


m: I don't think we should skip this but rather just log the warning instead if the clack.select prompt that halts the wizard execution. My thinking is that this might even be valuable information for agents.

Lms24 · 2026-01-08T10:50:58Z

src/nextjs/nextjs-wizard.ts

+  // Skip CI setup in skip-auth mode
+  if (!skipAuth) {


m: same here. I think a log message that users/agents need to configure CI after the wizard finished instead of the prompt, is better than entirely skipping this step, no?

Lms24 · 2026-01-08T10:53:32Z

src/nextjs/templates.ts

+# Your Sentry DSN (from Project Settings > Client Keys)
+# Used on the server-side
+SENTRY_DSN=
+
+# Your Sentry DSN for client-side (same value as SENTRY_DSN)
+# The NEXT_PUBLIC_ prefix exposes this to the browser
+NEXT_PUBLIC_SENTRY_DSN=


m: isn't it enough to just always set NEXT_PUBLIC_SENTRY_DSN? I think having one DSN env variable would be much less friction than two. Especially because it would tempt users to use different DSNs, when we don't recommend this in docs/other setup guides.

Lms24 · 2026-01-08T10:55:56Z

CHANGELOG.md

We don't update CHANGELOG.md anymore. Instead, you can customize the PR description and put the custom description into a

### Changelog Entry your description

section

Lms24 · 2026-01-08T11:07:46Z

Also, please add an e2e test that covers the agentic setup flow so that we have a good picture of what kind of file output we expect from this flow.

Lms24 · 2026-01-08T11:09:41Z

bin.ts

+    'mcp-cursor': {
+      default: false,
+      describe: 'Add MCP config for Cursor (used with --skip-auth)',
+      type: 'boolean',
+    },
+    'mcp-vscode': {
+      default: false,
+      describe: 'Add MCP config for VS Code (used with --skip-auth)',
+      type: 'boolean',
+    },
+    'mcp-claude': {
+      default: false,
+      describe: 'Add MCP config for Claude Code (used with --skip-auth)',
+      type: 'boolean',
+    },
+    'mcp-opencode': {
+      default: false,
+      describe: 'Add MCP config for OpenCode (used with --skip-auth)',
+      type: 'boolean',
+    },
+    'mcp-jetbrains': {
+      default: false,
+      describe: 'Show MCP config for JetBrains IDEs (used with --skip-auth)',
+      type: 'boolean',
+    },


Instead of adding 5 (or more in the future?) individual options, what about one combined option?

--mcp claude,cursor,jetbrains # or --mcp cursor # or --mcp cursor --mcp jetbrains

I think yargs handles all of these formats automatically, so we only need to adjust how we read these options (as an array of strings, rather than boolean flags, I presume)

Lms24 · 2026-01-08T11:13:55Z

bin.ts

+    'skip-auth': {
+      default: false,
+      describe:
+        'Skip Sentry authentication and use environment variable placeholders. Enables fully headless CLI operation.',


For the time being, let's prefix all these options with something like

Suggested change

'skip-auth': {

default: false,

describe:

'Skip Sentry authentication and use environment variable placeholders. Enables fully headless CLI operation.',

'skip-auth': {

default: false,

describe:

'[NextJS only] Skip Sentry authentication and use environment variable placeholders. Enables fully headless CLI operation.',

Users can call npx @sentry/wizard --help and might be confused about why this flag does nothing in e.g. the nuxt or sveltekit wizard.

Which brings me to my last point (for now):

Long-term, we should definitely bring all of these options to all our wizards. I fully understand that trialing this in the most used one makes sense but I really want to avoid the other flows falling behind. We'Ve had that before and it led to sub-par wizard experiences for non-NextJS users. Though let's tackle this in individual PRs please 😅

Lms24 · 2026-01-08T11:15:23Z

Oh yea, speaking of --help, the e2e test needs adjustments for whatever options we settle on.

Address PR review feedback: 1. Revert CHANGELOG.md - use PR description instead 2. Simplify to single NEXT_PUBLIC_SENTRY_DSN env var (works for both server and client) 3. Consolidate MCP flags into single --mcp array option: --mcp cursor,vscode or --mcp cursor --mcp vscode 4. Make all flags work independently (not tied to --skip-auth): - --tracing, --replay, --logs: use flag if set, prompt otherwise - --tunnel-route: use flag if set, prompt otherwise - --example-page: use flag if set, prompt otherwise (defaults to false in skip-auth mode) 5. Turbopack warning: log as warning in skip-auth mode instead of skip 6. CI setup: show helpful log message in skip-auth mode instead of skip

Lms24 reviewed Jan 8, 2026

View reviewed changes

Uh oh!

feat(nextjs): Add --skip-auth flag for headless CLI operation #1183

Are you sure you want to change the base?

feat(nextjs): Add --skip-auth flag for headless CLI operation #1183

Conversation

codyde commented Jan 8, 2026

Summary

New CLI Flags

Example Usage

Behavior in --skip-auth Mode

Generated .env.example

Use Cases

Testing

Uh oh!

github-actions bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Semver Impact of This PR

📋 Changelog Preview

New Features ✨

Cloudflare

Mcp

Other

Bug Fixes 🐛

Build / dependencies / internal 🔧

Deps

Test

Other

Other

Uh oh!

Lms24 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Lms24 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Lms24 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Lms24 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Lms24 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Lms24 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Lms24 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Lms24 commented Jan 8, 2026

Uh oh!

Lms24 Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Lms24 Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Lms24 commented Jan 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Behavior in `--skip-auth` Mode

Generated `.env.example`

github-actions bot commented Jan 8, 2026 •

edited

Loading

Lms24 left a comment •

edited

Loading

Lms24 Jan 8, 2026 •

edited

Loading

Lms24 Jan 8, 2026 •

edited

Loading