feat(init): Allow agent init without implicit app selection by djgould · Pull Request #244 · clerk/cli

djgould · 2026-04-29T14:35:54Z

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 · 2026-04-29T14:36:00Z

🦋 Changeset detected

Latest commit: 230a35b

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 · 2026-04-29T15:30:44Z

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: 358a38b3-b4a7-4f9e-aaaf-4c084af4cb6f

📥 Commits

Reviewing files that changed from the base of the PR and between 0b6092f and 230a35b.

📒 Files selected for processing (2)

.changeset/agent-init-keyless.md
packages/cli-core/src/commands/init/index.ts

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

.changeset/agent-init-keyless.md

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

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

📝 Walkthrough

Walkthrough

The pull request changes clerk init agent-mode behavior: agent detection is centralized and used to skip confirmations and disallow interactive login. Keyless decision logic is refactored into resolveKeylessMode so agent mode enables keyless only when no real app target exists (provided via --app or linked profile). In agent mode, non-keyless frameworks without a real app target now emit manual setup instructions instead of auto-selecting/creating an app. Authentication/link flows, error handling for missing platform keys, tests, integration scenarios, and docs/changesets are updated to match the new branching and terminology.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% 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 init without implicit app selection/creation, which is the central feature described across all modified files.
Description check	✅ Passed	The description is directly related to the changeset, covering the three core changes: agent init classification into modes, keyless usage, and avoidance of implicit app selection.
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

_{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 · 2026-04-29T15:51:52Z

+
+    // Auto-keyless is scoped to bootstrap (new-project) flows only in human
+    // mode. Existing projects keep the authenticated flow so real keys can be
+    // pulled unless an agent explicitly chooses keyless by omitting an app.


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

rafa-thayto · 2026-04-29T18:01:17Z

+    throwUsageError(
+      "clerk init in agent mode requires CLERK_PLATFORM_API_KEY or a valid stored session when using a real Clerk application. Pass --app only with auth available, or omit --app for keyless-capable frameworks.",
+    );
+  }


This throws USAGE_ERROR but it is actually an auth problem, not a syntax issue. Agents that branch on error codes (as the ERROR_CODE JSDoc suggests) would misinterpret this as a bad command instead of missing credentials.

Suggested change

}

throwUsageError(

"clerk init in agent mode requires CLERK_PLATFORM_API_KEY or a valid stored session when using a real Clerk application. Pass --app only with auth available, or omit --app for keyless-capable frameworks.",

undefined,

ERROR_CODE.AUTH_REQUIRED,

);

rafa-thayto · 2026-04-29T18:01:17Z

-    "    clerk auth login",
-    "    clerk link",
+    "    clerk init --app <app_id>",
    "    clerk env pull",


Since clerk init --app <app_id> already runs link + env pull internally, the separate clerk env pull line is redundant here and might confuse agents into running it twice.

Suggested change

" clerk env pull",

" clerk init --app <app_id>",

rafa-thayto · 2026-04-29T18:01:26Z

@@ -113,12 +123,15 @@ export async function init(options: InitOptions = {}) {

  if (alreadySetUp) {
    log.success("\nClerk is already set up in this project.");


This prints "Clerk is already set up" (success) and then the manual setup block tells the agent to run more commands. An agent might stop at the success message and never configure API keys.

Consider making the messaging unambiguous based on the mode:

Suggested change

log.success("\nClerk is already set up in this project.");

if (alreadySetUp) {

if (agent && manualSetup) {

log.info("\nClerk SDK and scaffold files are already in place, but API keys are not configured.");

printBootstrapManualSetupInfo(ctx.framework.name);

} else {

log.success("\nClerk is already set up in this project.");

}

Allow agent init without implicit app selection

13a59bf

djgould changed the title ~~[codex] Allow agent init without implicit app selection~~ feat(init): Allow agent init without implicit app selection Apr 29, 2026

Merge branch 'main' into codex/agent-init-keyless

0b6092f

djgould marked this pull request as ready for review April 29, 2026 15:25

djgould commented Apr 29, 2026

View reviewed changes

kylemac requested review from rafa-thayto and wyattjoh April 29, 2026 15:55

djgould added 2 commits April 29, 2026 12:04

Add changeset for agent init keyless flow

d69f33f

Merge branch 'main' into codex/agent-init-keyless

230a35b

rafa-thayto reviewed Apr 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat(init): Allow agent init without implicit app selection#244
djgould wants to merge 4 commits intomainfrom
codex/agent-init-keyless

djgould commented Apr 29, 2026

Uh oh!

changeset-bot Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Apr 29, 2026 •

edited

Loading

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

djgould Apr 29, 2026

Uh oh!

rafa-thayto Apr 29, 2026

Uh oh!

rafa-thayto Apr 29, 2026

Uh oh!

rafa-thayto Apr 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -113,12 +123,15 @@ export async function init(options: InitOptions = {}) {

		if (alreadySetUp) {
		log.success("\nClerk is already set up in this project.");

-    log.success("\nClerk is already set up in this project.");
+  if (alreadySetUp) {
+    if (agent && manualSetup) {
+      log.info("\nClerk SDK and scaffold files are already in place, but API keys are not configured.");
+      printBootstrapManualSetupInfo(ctx.framework.name);
+    } else {
+      log.success("\nClerk is already set up in this project.");
+    }

Conversation

djgould commented Apr 29, 2026

Summary

Validation

Uh oh!

changeset-bot Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

djgould Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

rafa-thayto Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

rafa-thayto Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

rafa-thayto Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Apr 29, 2026 •

edited

Loading

coderabbitai Bot commented Apr 29, 2026 •

edited

Loading