feat: make --keyless an opt-in flag on clerk init

[rafa-thayto]

Summary

• clerk init now always authenticates and links a real Clerk application by default. The previous silent fallback to auto-generated dev keys (when run unauthenticated on a keyless-capable framework) is removed.
• --keyless is the opt-in flag for the keyless flow. On a non-keyless framework it exits with a usage error.
• -y no longer bypasses authentication — it skips y/n confirmations only. Without --keyless, an unauthenticated user is still prompted to log in via the browser.
• Agent mode without --keyless or --app prints manual setup guidance instead of silently generating dev keys (agents can't run interactive OAuth).

Internal

• The keyless + manualSetup boolean pair is replaced by an InitStrategy union ("keyless" | "manual" | "authenticate") so the post-scaffold dispatch is exhaustive.
• Auth-related I/O (isAuthenticated, resolveProfile) is gated behind !optsKeyless so --keyless skips disk reads it doesn't need.
• Test fixtures DRYed via shared KEYLESS_CTX constant + mockBootstrapTo / mockExistingProject / mockMiddlewareScaffold helpers — collapses ~140 lines of repeated setup.

Test plan

• bun run format clean
• bun run lint clean
• bun run typecheck clean
• bun run test — 97/97 pass (47 in init/index.test.ts)
• bun run build succeeds
• bun run build:compile succeeds; compiled dist/clerk init --help shows --keyless flag and example
• Manual: run clerk init in a fresh Next.js project with no credentials → should prompt browser login
• Manual: run clerk init --keyless in a fresh Next.js project → should generate dev keys without prompting login
• Manual: run clerk init --keyless in a Vue project → should exit with usage error
• Manual: run clerk init -y in a fresh Next.js project with no credentials → should still prompt browser login (not skip auth)

[changeset-bot]

🦋 Changeset detected

Latest commit: 98c6b4d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR restructures how clerk init handles authentication and keyless development keys on keyless-capable frameworks. The new --keyless flag makes keyless mode explicit opt-in; by default, the command authenticates and links a real Clerk application. The implementation introduces a strategy-based execution model that selects between "authenticate", "keyless", or "manual" paths based on authentication state, framework support, and user options. All scenarios—interactive and agent-mode runs—are covered by expanded test assertions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the primary change: making --keyless an opt-in flag on clerk init, which matches the main objective of the PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description clearly relates to the changeset, explaining the new --keyless opt-in flag, authentication behavior changes, and internal refactoring with specific implementation details.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[djgould]

LGTM