feat(init): Allow agent init without implicit app selection

[djgould]

Summary

• classify agent init runs into real-app, keyless, or manual setup modes
• use keyless for keyless-capable frameworks when no app target exists
• avoid implicit app selection/creation and fail real-app agent runs without auth guidance

Validation

• bun test packages/cli-core/src/commands/init/index.test.ts packages/cli-core/src/commands/link/index.test.ts packages/cli-core/src/test/integration/agent-mode.test.ts
• bun run --filter @clerk/cli-core typecheck
• bun run --filter @clerk/cli-core format:check
• bunx oxfmt --check skills/clerk/SKILL.md skills/clerk/references/agent-mode.md
• git diff --check

[changeset-bot]

🦋 Changeset detected

Latest commit: a6c44d6

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

This PR includes changesets to release 1 package

Name	Type
clerk	Patch

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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e034d800-930f-4a06-bc8a-0ac80ce8f46b

📥 Commits

Reviewing files that changed from the base of the PR and between 0d2c02d and a6c44d6.

📒 Files selected for processing (6)

• packages/cli-core/src/commands/init/README.md
• packages/cli-core/src/commands/init/index.test.ts
• packages/cli-core/src/commands/init/index.ts
• packages/cli-core/src/test/integration/agent-mode.test.ts
• skills/clerk-cli/SKILL.md
• skills/clerk-cli/references/agent-mode.md

✅ Files skipped from review due to trivial changes (1)

• skills/clerk-cli/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/cli-core/src/commands/init/index.test.ts

---

📝 Walkthrough

Walkthrough

This PR updates the Clerk CLI's init command to support agent mode without requiring an explicit --app argument. The authentication and linking flow is refactored to conditionally perform app operations based on whether a real app target exists. Keyless-capable frameworks use keyless mode when no app is provided; non-keyless frameworks print manual setup guidance instead of attempting automatic linking. Tests are expanded to validate keyless vs. non-keyless behavior in agent mode, and documentation is updated across README, integration tests, and reference guides to clarify the new control flow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% 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 accurately summarizes the main change: enabling agent mode initialization without requiring implicit app selection.
Description check	✅ Passed	The description is clearly related to the changeset, providing a concise summary of the key behavioral changes and validation steps.
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.

_{✏️ 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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

[djgould]

to be honest i'm not sure this is what we want, but its what we were doing before. i find the fact that clerk init doesn't require auth for bootstrapping and does require auth in existing projects a bit odd

[wyattjoh]

Refactoring resolveKeylessMode moved the if (!bootstrap) return false; early-return inside the if (ctx.framework.supportsKeyless) block. The non-keyless branch (which still ends in log.info("X requires API keys — keyless mode is not yet supported for this framework.")) is no longer guarded by bootstrap, so the log now fires on paths where keyless was never being considered:

• Human mode re-running clerk init in an existing Vue / Express / Fastify project (previously silent).
• Agent mode with --app on a non-keyless framework (the real-app flow is what's running; the user gets a misleading 'keyless not supported' note).
• The new agent manual-setup path, where printBootstrapManualSetupInfo already prints a clearer 'requires API keys — set them up manually' block. Users see two near-duplicate messages back-to-back.

The new integration test init prints manual setup for non-keyless framework without an app target in agent mode only asserts expect(stderr).toContain("clerk init --app <app_id>"), which passes despite the duplicate output, so the regression isn't caught.

Suggested fix: short-circuit on the non-keyless framework before the function does anything else, and let the caller own user-facing copy:

function resolveKeylessMode({...}): boolean {
  if (!ctx.framework.supportsKeyless) return false;
  if (agent) return !hasRealAppTarget;
  if (!bootstrap) return false;
  return !authed;
}

If the bootstrap-of-non-keyless framework hint is still wanted, emit it at the bootstrap call site (e.g., next to printBootstrapManualSetupInfo) rather than from inside the resolver. Either way, please add a regression test that asserts stderr does not contain keyless mode is not yet supported for an existing-project non-keyless human-mode run.