feat(init): create real app when authed in agent mode

[wyattjoh]

Summary

When clerk init runs in agent mode without --app and the user is already authenticated, the CLI now creates a real Clerk application named after the project and links it, instead of falling back to keyless setup. Previously an authed agent run created an unowned keyless app and wrote a deferred-claim breadcrumb, so the project ended up unlinked even though the user had logged in before the run; auto-claim only fired on a subsequent clerk auth login, which authed users had no reason to re-run. Keyless still runs in agent mode when the user is not authenticated.

The change adds a createIfMissing library option to link so the agent-mode autolink path can fall through to a deterministic create instead of the existing usage error, and threads a project-name derivation (package.json#name, --name, or directory basename) through init's authenticated branch.

Test plan

• bun run typecheck
• bun run lint
• bun run test
• Manual: clerk init --framework next --pm npm in agent mode while logged in → real app appears in the dashboard, .env.local has dev keys, clerk doctor reports linked
• Manual: same command while not logged in → keyless flow still runs, breadcrumb still written, original deferred-claim path still works on next clerk auth login

[changeset-bot]

🦋 Changeset detected

Latest commit: b175cd3

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]

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: 96294811-95d1-416a-a6ee-15885647d03e

📥 Commits

Reviewing files that changed from the base of the PR and between bc4212c and b175cd3.

📒 Files selected for processing (3)

• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/test/integration/agent-mode.test.ts

---

📝 Walkthrough

Walkthrough

This PR makes clerk init in agent mode create and link real Clerk applications when the runner is authenticated, otherwise preserving keyless behavior for unauthenticated runs. It adds a deriveProjectName helper and uses it from autoclaim and init flows to compute app names, introduces a createIfMissing option passed from init into link to auto-create apps, updates docs, and adjusts unit and integration tests to cover authenticated agent flows and app-creation behavior.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.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: creating a real app when authenticated in agent mode, which is the primary objective of this PR.
Description check	✅ Passed	The description is directly related to the changeset, explaining the motivation and implementation details of the authentication-dependent app creation behavior in agent mode.
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.}

---

_{Review rate limit: 4/5 reviews remaining, refill in 12 minutes.}

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

[Railly]

Reviewed locally. Logic checks out, autolink runs first to avoid duplicates, the guard still trips when createIfMissing is missing.

A couple things worth a look:

PLAPI accepts duplicate app names. Created two apps with the same name to confirm, different IDs each time. Agents running clerk init across multiple Next default projects will fill the dashboard with "my-app" entries. Worth either disambiguating the derived name or mentioning it in the changeset.

Also poked at createAndFetchApp and the second call is redundant. The raw POST /v1/platform/applications response already includes application_id, name, and a full instances[] array with instance_id, environment_type, secret_key, publishable_key. The follow-up GET /v1/platform/applications/{id} returns the same shape minus secret_key, so it actually drops information from the create response. Doesn't break anything because link only persists the instance ID and env pull fetches keys later, but it's an extra PLAPI round-trip per authed init that buys nothing. Easy to drop the second call, or leave a comment if it's defensive.

Otherwise looks good.