feat: auto-claim keyless applications on login by rafa-thayto · Pull Request #157 · clerk/cli

rafa-thayto · 2026-04-15T00:45:24Z

Summary

Add keyless application lifecycle (keyless.ts): create accountless apps via BAPI, write framework-specific keys to .env.local, manage .clerk/keyless.json claim token breadcrumb
Add autoclaim orchestrator (autoclaim.ts): after clerk auth login, detect keyless breadcrumb and automatically claim the application via PLAPI — never throws, returns discriminated union so login is never interrupted
Auto-pull environment variables after successful claim — no manual clerk env pull step needed
Extract shared linkApp() from autolink.ts for reuse by both autolink (key detection) and autoclaim (keyless claim)
Add claimApplication() PLAPI endpoint (POST /v1/platform/accountless_applications/claim)
Integrate keyless setup into clerk init bootstrap when user skips auth
Integrate autoclaim into clerk auth login with contextual warnings and next-steps per failure mode
Truncate app name to 50 chars to match backend validation limit

How it works

clerk init (skip auth) → creates accountless app, writes keys to .env.local, stores claim token in .clerk/keyless.json
Developer builds their app using temporary dev keys
clerk auth login → after OAuth, reads breadcrumb, calls claim endpoint, links app to account, auto-pulls env vars, clears breadcrumb
Failure handling: transient errors (5xx) preserve breadcrumb for retry on next login; terminal errors (404/403) clear it; env pull failures warn but don't block login

Cleanup pass (commit `6cda4f5`)

Applied KISS/DRY simplification across the new surface and touched neighboring code where it shared the same patterns. Net: -121 lines (107 insertions, 228 deletions).

plapi.ts: extracted shared plapiRequest<T> helper; 6 near-identical fetch-with-auth blocks (20 lines each) collapsed to 2–3 line call sites. Helper normalizes URL construction, query-param serialization, auth headers, PlapiError throw, and JSON parsing.
errors.ts: promoted errorMessage(unknown): string out of commands/doctor/checks.ts so autoclaim.ts and init/index.ts can reuse it instead of re-implementing error instanceof Error ? error.message : String(error) inline.
keyless.ts: replaced two TOCTOU Bun.file(...).exists() + read patterns with atomic .text().catch(() => "") / .json().catch(...); parallelized independent detectPublishableKeyName + detectSecretKeyName with Promise.all; factored .env.local / .clerk / keyless.json into named constants.
autoclaim.ts: table-driven classifyClaimError — replaced back-to-back error instanceof PlapiError && error.status === N branches with a TERMINAL_BY_STATUS: Record<number, Terminal["status"]> lookup.
Comments: removed file-level docstring blocks, section-header banners, and WHAT/narration comments from new files per house style (kept non-obvious WHY comments).
Tests: as never → as Profile, dropped the spies[] array in favor of explicit per-spy mockRestore(), deleted redundant setup commentary.

Test plan

9 unit tests for autoclaim (all status paths, breadcrumb preservation, env pull success/failure)
15 unit tests for keyless (BAPI calls, env writing, breadcrumb I/O, token parsing)
Login tests pass with autoclaim mocked
Full test suite passes (73 suites)
Lint, format, and typecheck clean
CI green after cleanup pass
Requires backend PLAPI claim endpoint to be deployed first (CLI gracefully no-ops if endpoint is unavailable)
E2E: clerk init -y → skip auth → verify .env.local and .clerk/keyless.json created → clerk auth login → verify app claimed, linked, and env vars refreshed

changeset-bot · 2026-04-17T17:11:46Z

🦋 Changeset detected

Latest commit: d90fd0a

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 · 2026-04-17T17:11:49Z

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: 49d72fb4-1407-475b-8a10-ef138f3c541a

📥 Commits

Reviewing files that changed from the base of the PR and between 2c93fe4 and d90fd0a.

📒 Files selected for processing (19)

.changeset/auto-claim.md
packages/cli-core/src/commands/auth/README.md
packages/cli-core/src/commands/auth/login.test.ts
packages/cli-core/src/commands/auth/login.ts
packages/cli-core/src/commands/doctor/checks.ts
packages/cli-core/src/commands/doctor/index.ts
packages/cli-core/src/commands/init/README.md
packages/cli-core/src/commands/init/heuristics.ts
packages/cli-core/src/commands/init/index.test.ts
packages/cli-core/src/commands/init/index.ts
packages/cli-core/src/lib/autoclaim.test.ts
packages/cli-core/src/lib/autoclaim.ts
packages/cli-core/src/lib/autolink.ts
packages/cli-core/src/lib/errors.ts
packages/cli-core/src/lib/keyless.test.ts
packages/cli-core/src/lib/keyless.ts
packages/cli-core/src/lib/next-steps.ts
packages/cli-core/src/lib/plapi.ts
packages/cli-core/src/test/lib/stubs.ts

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

.changeset/auto-claim.md
packages/cli-core/src/commands/doctor/index.ts
packages/cli-core/src/lib/keyless.test.ts

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

packages/cli-core/src/lib/errors.ts
packages/cli-core/src/test/lib/stubs.ts
packages/cli-core/src/lib/next-steps.ts
packages/cli-core/src/commands/init/heuristics.ts
packages/cli-core/src/commands/init/index.ts
packages/cli-core/src/commands/init/README.md
packages/cli-core/src/commands/auth/login.ts

📝 Walkthrough

Walkthrough

Adds end-to-end keyless autoclaim: new lib/autoclaim.ts (exports attemptAutoclaim, AutoclaimResult) and lib/keyless.ts (create accountless app, write keys to env, parse claim token, manage .clerk/keyless.json). plapi.ts gains claimApplication. autolink.ts gains linkApp and delegates linking. auth/login invokes autoclaim and routes NEXT_STEPS by claim result. NEXT_STEPS extended. Shared errorMessage helper extracted and reused. Numerous Bun tests and docs updated; init now performs keyless setup and writes temporary keys.

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 26.32% 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 'feat: auto-claim keyless applications on login' directly and concisely describes the main feature addition—automatic claiming of keyless applications upon user login.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, covering the keyless lifecycle, autoclaim orchestration, environment variable handling, and integration points with clear implementation details.
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

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

wyattjoh

Code Review — PR #157

Reviewed with Opus + Codex second-opinion validation.

Blocker

B1. .clerk/keyless.json stores a live claim token with no .gitignore protection(codex confirmed)
packages/cli-core/src/lib/keyless.ts:88-106 writes claimToken under .clerk/ in the user's project. Nothing in this PR (or clerk init today) appends .clerk/ to the project's .gitignore. A developer can git add . and commit the token to a public repo, at which point any third party can claim the app before the original developer logs in, hijacking an app that will later hold production workloads.

Suggestion: in setupKeylessApp or writeKeylessBreadcrumb, append .clerk/ to .gitignore if not already present (mirroring what create-next-app and similar tools do). Add a test that verifies the .gitignore update.

B2. Keyless init writes .env.local but post-claim pull writes the framework default, producing two env files with drifting keys
This is a cross-file interaction with existing code rather than a change in this PR alone, but the PR is where the regression becomes user-visible:

packages/cli-core/src/lib/keyless.ts:57-76 hardcodes const targetFile = join(cwd, ".env.local").
packages/cli-core/src/lib/framework.ts (unchanged) declares envFile: ".env" for Next.js, Astro, and Nuxt.
packages/cli-core/src/commands/env/pull.ts:30-46 (resolveTargetFile) prefers the framework-detected file.

Net effect on a Next.js project: .env.local written at init, .env written by pull after claim, same keys, different values.

Suggestion: use detectEnvFile(cwd) in writeKeysToEnvFile so there is one canonical target. Also update the JSDoc that references .env.local.

B3. Missing changeset
git diff main..HEAD -- .changeset/ is empty. This is a feat: PR touching @clerk/cli-core runtime. The Enforce Changeset workflow will block merge.

Major

M1. App name sent to backend uses basename(cwd).slice(0, 50) with no sanitization(codex confirmed)
packages/cli-core/src/lib/autoclaim.ts:32:

Leaks potentially-sensitive directory names to the Clerk platform API.
.slice(50) truncates on UTF-16 code units; an emoji or non-BMP char at the boundary produces an orphaned surrogate (400 on strict UTF-8 validators).
Backend-invalid chars are not sanitized.

Suggestion: derive the name from package.json#name or the git repo name with basename(cwd) as a fallback, and sanitize + byte-length-truncate before sending.

M2. attemptAutoclaim(cwd) threads cwd but tryPullEnv ignores it
autoclaim.ts:37-50 accepts a cwd argument for the breadcrumb but calls pull({}), which uses process.cwd() internally (pull.ts:53). Today's single call site passes process.cwd() so it is benign, but this is fragile. Either thread cwd through pull options or assert at entry.

M3. createAccountlessApp has no timeout or abort; clerk init hangs on captive portal / slow BAPI(codex confirmed)
packages/cli-core/src/lib/keyless.ts:35-52 and packages/cli-core/src/commands/init/index.ts:272-287: fetch(...) has no AbortController. On slow/broken networks, withSpinner hangs indefinitely. log.debug is only visible with --verbose, so users see nothing.

M4. setupKeylessApp swallows all errors while success copy still renders(codex confirmed)
commands/init/index.ts:270-287 wraps the body in try { ... } catch { log.debug(...) }. Even on filesystem errors, parseClaimToken throws, or the fetch fails, printKeylessInfo still tells the user "Your app is ready with development keys in .env.local". Distinguish expected network failures from unexpected bugs and suppress the success message on failure.

M5. classifyClaimError semantic mismatch and aggressive breadcrumb-clear
autoclaim.ts:62-74 maps 403 to already_claimed, but the message at login.ts:128-132 says "your account does not have an active organization". Name and message disagree; rename the status (e.g. no_organization). Also, 404 unconditionally clears the breadcrumb; a transient DNS blip that returns 404 would destroy the retry signal.

Minor

readKeylessBreadcrumb (keyless.ts:108-119) has no schema validation; a malformed-but-JSON file yields {claimToken: undefined} and autoclaim.ts:33 will POST {token: undefined}.
parseClaimToken uses https://placeholder.com as the synthetic URL base (keyless.ts:81-87); prefer https://example.invalid (RFC 6761).
Em-dashes added in login.ts:130-131,163 and autoclaim.ts:7 (global style rule).
handleAutoclaim prints log.success then log.warn then outro (login.ts:117-124,135-148); noisy ordering.
No retry for 5xx / 429 despite the design claim that "transient failures preserve breadcrumb for retry on next login" (autoclaim.ts:28-36); a short in-process retry with backoff would save users a manual re-login.

Nits

CLAIM_WARNINGS could be an explicit object-literal map of the three warning statuses.
log.info("Environment variables written to .env.local") will be wrong once B2 is fixed.
Test expect(parsed.name).toBeTruthy() (autoclaim.test.ts:164) is too loose; assert the exact truncation.
CI refactor (composite action, workflow_call) is bundled into a feat: PR; splitting would simplify bisect.

Positives

AutoclaimResult discriminated union is cleanly typed and enables exhaustive handling in loginNextSteps. attemptAutoclaim never throws (the type system enforces it). linkApp extraction in autolink.ts is a good refactor. Test coverage for the orchestrator is thorough: all status paths, breadcrumb clear/preserve semantics, env-pull success/failure, linkApp invocation, and request body shape.

B1: add .clerk/ to .gitignore in writeKeylessBreadcrumb to prevent claim token from being committed to public repos B2: use detectEnvFile(cwd) in writeKeysToEnvFile so init and claim write to the same env file (e.g. .env for Next.js, not .env.local) B3: add changeset (minor) for the autoclaim feature M1: derive app name from package.json#name with basename fallback; byte-length-truncate to 50 to avoid surrogate issues M2: thread cwd through tryPullEnv -> pull() instead of relying on process.cwd() internally M3: add 15s AbortController timeout to createAccountlessApp to prevent hanging on captive portal / slow BAPI M4: move printKeylessInfo() inside try block so success copy is suppressed on failure M5: rename already_claimed -> no_organization to match the actual 403 semantic (no active organization); fix em-dashes in messages nit: use https://example.invalid instead of https://placeholder.com nit: add schema validation to readKeylessBreadcrumb nit: tighten autoclaim test name assertion (exact value, not truthy) nit: add gitignore idempotency test + wrong-shape breadcrumb test docs(changeset): Automatically claim and link keyless applications on clerk auth login

wyattjoh

Code review

Substantial new surface (keyless.ts, autoclaim.ts) plus a clean plapi.ts refactor. Core design — discriminated AutoclaimResult, never-throws contract, breadcrumb-preserve-on-transient — is sound. A handful of issues worth tightening before merge: one user-facing inaccuracy (.env.local message), one misleading API parameter (pull({ cwd })), and a few error-handling edges (retry loops, corrupted breadcrumb recovery, silent keyless creation failures).

B1: add .clerk/ to .gitignore in writeKeylessBreadcrumb to prevent claim token from being committed to public repos B2: use detectEnvFile(cwd) in writeKeysToEnvFile so init and claim write to the same env file (e.g. .env for Next.js, not .env.local) B3: add changeset (minor) for the autoclaim feature M1: derive app name from package.json#name with basename fallback; byte-length-truncate to 50 to avoid surrogate issues M2: thread cwd through tryPullEnv -> pull() instead of relying on process.cwd() internally M3: add 15s AbortController timeout to createAccountlessApp to prevent hanging on captive portal / slow BAPI M4: move printKeylessInfo() inside try block so success copy is suppressed on failure M5: rename already_claimed -> no_organization to match the actual 403 semantic (no active organization); fix em-dashes in messages nit: use https://example.invalid instead of https://placeholder.com nit: add schema validation to readKeylessBreadcrumb nit: tighten autoclaim test name assertion (exact value, not truthy) nit: add gitignore idempotency test + wrong-shape breadcrumb test docs(changeset): Automatically claim and link keyless applications on clerk auth login

HIGH: - printKeylessInfo now accepts envFile param so Next.js/Astro/Nuxt users see the correct file name (.env) instead of hardcoded .env.local - drop cwd option from EnvPullOptions — resolveAppContext internally uses process.cwd() so a partial cwd thread is misleading; only caller passes process.cwd() already MEDIUM: - broaden terminal 4xx: all 4xx except 408/429 clear breadcrumb to prevent infinite retry loops on 400/409/422 responses - readKeylessBreadcrumb now clears corrupted/wrong-shape breadcrumb files so the user can recover via re-running clerk init - setupKeylessApp escalates creation failure from log.debug to log.warn with recovery hint (clerk auth login + clerk link) - createAccountlessApp throws BapiError instead of plain Error to match project error-handling protocol LOW: - remove unused AUTOCLAIM_FAILED error code - switch to char-based truncation (Array.from) for app name — simpler than byte-slice and matches likely backend char semantics - add RFC 6761 comment on example.invalid sentinel in parseClaimToken Tests: add 400/429 terminal/retryable tests; verify wrong-shape breadcrumb is cleared from disk; update BapiError assertion

B1: add .clerk/ to .gitignore in writeKeylessBreadcrumb to prevent claim token from being committed to public repos B2: use detectEnvFile(cwd) in writeKeysToEnvFile so init and claim write to the same env file (e.g. .env for Next.js, not .env.local) B3: add changeset (minor) for the autoclaim feature M1: derive app name from package.json#name with basename fallback; byte-length-truncate to 50 to avoid surrogate issues M2: thread cwd through tryPullEnv -> pull() instead of relying on process.cwd() internally M3: add 15s AbortController timeout to createAccountlessApp to prevent hanging on captive portal / slow BAPI M4: move printKeylessInfo() inside try block so success copy is suppressed on failure M5: rename already_claimed -> no_organization to match the actual 403 semantic (no active organization); fix em-dashes in messages nit: use https://example.invalid instead of https://placeholder.com nit: add schema validation to readKeylessBreadcrumb nit: tighten autoclaim test name assertion (exact value, not truthy) nit: add gitignore idempotency test + wrong-shape breadcrumb test docs(changeset): Automatically claim and link keyless applications on clerk auth login

HIGH: - printKeylessInfo now accepts envFile param so Next.js/Astro/Nuxt users see the correct file name (.env) instead of hardcoded .env.local - drop cwd option from EnvPullOptions — resolveAppContext internally uses process.cwd() so a partial cwd thread is misleading; only caller passes process.cwd() already MEDIUM: - broaden terminal 4xx: all 4xx except 408/429 clear breadcrumb to prevent infinite retry loops on 400/409/422 responses - readKeylessBreadcrumb now clears corrupted/wrong-shape breadcrumb files so the user can recover via re-running clerk init - setupKeylessApp escalates creation failure from log.debug to log.warn with recovery hint (clerk auth login + clerk link) - createAccountlessApp throws BapiError instead of plain Error to match project error-handling protocol LOW: - remove unused AUTOCLAIM_FAILED error code - switch to char-based truncation (Array.from) for app name — simpler than byte-slice and matches likely backend char semantics - add RFC 6761 comment on example.invalid sentinel in parseClaimToken Tests: add 400/429 terminal/retryable tests; verify wrong-shape breadcrumb is cleared from disk; update BapiError assertion

wyattjoh

Solid feature overall. The main concerns are an existing-session path that bypasses auto-claim entirely, a raw fetch() call that skips the project's loggedFetch wrapper, a success-log UX wart where both a success line and a Run env pull manually warn can print together, and an overly broad 4xx-is-terminal classifier. See inline comments.

B1: add .clerk/ to .gitignore in writeKeylessBreadcrumb to prevent claim token from being committed to public repos B2: use detectEnvFile(cwd) in writeKeysToEnvFile so init and claim write to the same env file (e.g. .env for Next.js, not .env.local) B3: add changeset (minor) for the autoclaim feature M1: derive app name from package.json#name with basename fallback; byte-length-truncate to 50 to avoid surrogate issues M2: thread cwd through tryPullEnv -> pull() instead of relying on process.cwd() internally M3: add 15s AbortController timeout to createAccountlessApp to prevent hanging on captive portal / slow BAPI M4: move printKeylessInfo() inside try block so success copy is suppressed on failure M5: rename already_claimed -> no_organization to match the actual 403 semantic (no active organization); fix em-dashes in messages nit: use https://example.invalid instead of https://placeholder.com nit: add schema validation to readKeylessBreadcrumb nit: tighten autoclaim test name assertion (exact value, not truthy) nit: add gitignore idempotency test + wrong-shape breadcrumb test docs(changeset): Automatically claim and link keyless applications on clerk auth login

HIGH: - printKeylessInfo now accepts envFile param so Next.js/Astro/Nuxt users see the correct file name (.env) instead of hardcoded .env.local - drop cwd option from EnvPullOptions — resolveAppContext internally uses process.cwd() so a partial cwd thread is misleading; only caller passes process.cwd() already MEDIUM: - broaden terminal 4xx: all 4xx except 408/429 clear breadcrumb to prevent infinite retry loops on 400/409/422 responses - readKeylessBreadcrumb now clears corrupted/wrong-shape breadcrumb files so the user can recover via re-running clerk init - setupKeylessApp escalates creation failure from log.debug to log.warn with recovery hint (clerk auth login + clerk link) - createAccountlessApp throws BapiError instead of plain Error to match project error-handling protocol LOW: - remove unused AUTOCLAIM_FAILED error code - switch to char-based truncation (Array.from) for app name — simpler than byte-slice and matches likely backend char semantics - add RFC 6761 comment on example.invalid sentinel in parseClaimToken Tests: add 400/429 terminal/retryable tests; verify wrong-shape breadcrumb is cleared from disk; update BapiError assertion

- Run autoclaim on agent-mode existing-session path (not just post-OAuth) - Use loggedFetch in createAccountlessApp (bapi tag; verbose shows URL+body) - Drop duplicate log.warn for failed env pull (next-steps already covers it) - Narrow 4xx terminal classification to explicit 404/403 only; all other errors preserve the breadcrumb for retry on next login - Use Intl.Segmenter for grapheme-safe name truncation - Update init/README.md and auth/README.md with keyless API endpoints and breadcrumb lifecycle docs

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/keyless.ts`:
- Around line 117-126: The writeKeylessBreadcrumb function currently writes the
breadcrumb file before ensuring the .gitignore entry, risking an unignored
secret if the process fails; change the order or add cleanup: call
ensureGitignoreEntry(cwd, BREADCRUMB_DIR + "/") before writing the file, then
create the directory and write the breadcrumb to breadcrumbPath(cwd);
alternatively, if you prefer to keep the current order, wrap the
Bun.write(breadcrumbPath(cwd), ...) call in try/catch and on any failure remove
the partial file (using breadcrumbPath(cwd)) so no unignored token remains.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6f39bbd3-a4c1-4dae-b020-21d3ad603374

📥 Commits

Reviewing files that changed from the base of the PR and between 55ea73e and da939c9.

📒 Files selected for processing (18)

.changeset/auto-claim.md
packages/cli-core/src/commands/auth/README.md
packages/cli-core/src/commands/auth/login.test.ts
packages/cli-core/src/commands/auth/login.ts
packages/cli-core/src/commands/doctor/checks.ts
packages/cli-core/src/commands/doctor/index.ts
packages/cli-core/src/commands/init/README.md
packages/cli-core/src/commands/init/heuristics.ts
packages/cli-core/src/commands/init/index.ts
packages/cli-core/src/lib/autoclaim.test.ts
packages/cli-core/src/lib/autoclaim.ts
packages/cli-core/src/lib/autolink.ts
packages/cli-core/src/lib/errors.ts
packages/cli-core/src/lib/keyless.test.ts
packages/cli-core/src/lib/keyless.ts
packages/cli-core/src/lib/next-steps.ts
packages/cli-core/src/lib/plapi.ts
packages/cli-core/src/test/lib/stubs.ts

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

.changeset/auto-claim.md
packages/cli-core/src/commands/auth/login.test.ts
packages/cli-core/src/commands/init/README.md
packages/cli-core/src/commands/auth/login.ts

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

packages/cli-core/src/lib/errors.ts
packages/cli-core/src/lib/plapi.ts
packages/cli-core/src/lib/next-steps.ts
packages/cli-core/src/commands/init/heuristics.ts
packages/cli-core/src/lib/autoclaim.test.ts
packages/cli-core/src/lib/autoclaim.ts
packages/cli-core/src/commands/init/index.ts
packages/cli-core/src/lib/keyless.test.ts

- Use loggedFetch in createAccountlessApp (bapi tag, --verbose support) - Write .gitignore entry before breadcrumb file to prevent exposure on interrupted writes - Run autoclaim on agent-mode existing-session path, not just post-OAuth - Narrow 4xx terminal classification to explicit 404/403 only; all other errors preserve the breadcrumb for retry on next login - Drop duplicate log.warn for failed env pull (next-steps covers it) - Use Intl.Segmenter for grapheme-safe app name truncation - Remove unused AUTOCLAIM_FAILED error code - Pass envFile from ctx to printKeylessInfo and setupKeylessApp so the correct env file is shown per framework (Next.js/.env vs .env.local) - Corrupt keyless.json now cleared on read so fresh setup can proceed - Add isAuthenticated() credential-presence check for init keyless flow - Update init/README.md and auth/README.md with keyless API endpoints and breadcrumb lifecycle documentation

Add machine-readable error code for autoclaim failures, available for agent mode and CI error classification.

Add PLAPI client function for POST /v1/platform/accountless_applications/claim. Sends claim token and app name, returns the claimed Application.

Extract profile-building logic from autolink() into a reusable linkApp() function. This allows both autolink (key detection) and autoclaim (keyless claim) to share the same profile persistence code.

Add keyless.ts for managing accountless Clerk applications: - createAccountlessApp(): calls BAPI to create app with no auth - writeKeysToEnvFile(): writes framework-specific keys to .env.local - parseClaimToken(): extracts token from claim URL - Breadcrumb I/O: read/write/clear .clerk/keyless.json Includes 15 unit tests covering all functions and edge cases.

Add autoclaim.ts that detects keyless projects and claims them automatically after clerk auth login. Never throws — returns a discriminated union (claimed|not_found|already_claimed|failed|not_keyless) so the login flow is never interrupted. Key behaviors: - Truncates app name to 50 chars (backend limit) - Transient errors (5xx) preserve breadcrumb for retry - Terminal errors (404/403) clear breadcrumb Includes 8 unit tests covering all status paths.

When bootstrap mode skips authentication, create an accountless app via BAPI, write keys to .env.local, and store the claim token in .clerk/keyless.json for autoclaim on next login. Also simplifies the keyless info message to promote the autoclaim flow instead of requiring manual clerk link + env pull.

Wire autoclaim into the login flow with improved UX: - Specific warning messages per failure cause (expired token, missing org, transient error) instead of generic fallback - Contextual next-steps based on claim result: manual link for terminal failures, retry guidance for transient errors - Mock autoclaim in login tests to isolate from transitive deps

After a successful autoclaim, automatically run `env pull` to refresh .env.local with the claimed app's keys — no manual step needed.

- Extract shared plapiRequest<T> helper; collapse 6 PLAPI functions to 2-3 lines each (6 near-duplicate fetch blocks → one) - Promote errorMessage() from doctor/checks.ts to lib/errors.ts so it can be shared with autoclaim.ts and init/index.ts - Replace two TOCTOU file.exists()+read patterns in keyless.ts with atomic .text()/.json() catch-ENOENT variants - Parallelize detectPublishableKeyName + detectSecretKeyName in writeKeysToEnvFile (independent I/O) - Table-drive classifyClaimError (404/403 status → result mapping) - Drop file-level docstrings, section-header banners, and WHAT/ narration comments across new files per house style

- Use loggedFetch in createAccountlessApp (bapi tag, --verbose support) - Write .gitignore entry before breadcrumb file to prevent exposure on interrupted writes - Run autoclaim on agent-mode existing-session path, not just post-OAuth - Narrow 4xx terminal classification to explicit 404/403 only; all other errors preserve the breadcrumb for retry on next login - Drop duplicate log.warn for failed env pull (next-steps covers it) - Use Intl.Segmenter for grapheme-safe app name truncation - Remove unused AUTOCLAIM_FAILED error code - Pass envFile from ctx to printKeylessInfo and setupKeylessApp so the correct env file is shown per framework (Next.js/.env vs .env.local) - Corrupt keyless.json now cleared on read so fresh setup can proceed - Add isAuthenticated() credential-presence check for init keyless flow - Update init/README.md and auth/README.md with keyless API endpoints and breadcrumb lifecycle documentation

- autoclaim: wrap linkApp in tryLinkApp helper so a local config write failure after a successful server-side claim cannot surface as a failed login (preserves the never-throws contract) - login: clarify that failed-autoclaim retry happens on next `clerk auth login`, not just any subsequent command - keyless: raise breadcrumb shape-mismatch auto-repair log from debug to warn so users running without --verbose see the fix - init: differentiate AbortError (15s timeout) with a specific "Could not reach api.clerk.com within 15s" message - init tests: stub createAccountlessApp / writeKeysToEnvFile / writeKeylessBreadcrumb so keyless init tests stop minting real accountless apps against production BAPI on every test run

rafa-thayto · 2026-04-15T00:45:24Z

Summary

Add keyless application lifecycle (keyless.ts): create accountless apps via BAPI, write framework-specific keys to .env.local, manage .clerk/keyless.json claim token breadcrumb
Add autoclaim orchestrator (autoclaim.ts): after clerk auth login, detect keyless breadcrumb and automatically claim the application via PLAPI — never throws, returns discriminated union so login is never interrupted
Auto-pull environment variables after successful claim — no manual clerk env pull step needed
Extract shared linkApp() from autolink.ts for reuse by both autolink (key detection) and autoclaim (keyless claim)
Add claimApplication() PLAPI endpoint (POST /v1/platform/accountless_applications/claim)
Integrate keyless setup into clerk init bootstrap when user skips auth
Integrate autoclaim into clerk auth login with contextual warnings and next-steps per failure mode
Truncate app name to 50 chars to match backend validation limit

How it works

clerk init (skip auth) → creates accountless app, writes keys to .env.local, stores claim token in .clerk/keyless.json
Developer builds their app using temporary dev keys
clerk auth login → after OAuth, reads breadcrumb, calls claim endpoint, links app to account, auto-pulls env vars, clears breadcrumb
Failure handling: transient errors (5xx) preserve breadcrumb for retry on next login; terminal errors (404/403) clear it; env pull failures warn but don't block login

Cleanup pass (commit `6cda4f5`)

Applied KISS/DRY simplification across the new surface and touched neighboring code where it shared the same patterns. Net: -121 lines (107 insertions, 228 deletions).

plapi.ts: extracted shared plapiRequest<T> helper; 6 near-identical fetch-with-auth blocks (20 lines each) collapsed to 2–3 line call sites. Helper normalizes URL construction, query-param serialization, auth headers, PlapiError throw, and JSON parsing.
errors.ts: promoted errorMessage(unknown): string out of commands/doctor/checks.ts so autoclaim.ts and init/index.ts can reuse it instead of re-implementing error instanceof Error ? error.message : String(error) inline.
keyless.ts: replaced two TOCTOU Bun.file(...).exists() + read patterns with atomic .text().catch(() => "") / .json().catch(...); parallelized independent detectPublishableKeyName + detectSecretKeyName with Promise.all; factored .env.local / .clerk / keyless.json into named constants.
autoclaim.ts: table-driven classifyClaimError — replaced back-to-back error instanceof PlapiError && error.status === N branches with a TERMINAL_BY_STATUS: Record<number, Terminal["status"]> lookup.
Comments: removed file-level docstring blocks, section-header banners, and WHAT/narration comments from new files per house style (kept non-obvious WHY comments).
Tests: as never → as Profile, dropped the spies[] array in favor of explicit per-spy mockRestore(), deleted redundant setup commentary.

Test plan

9 unit tests for autoclaim (all status paths, breadcrumb preservation, env pull success/failure)
15 unit tests for keyless (BAPI calls, env writing, breadcrumb I/O, token parsing)
Login tests pass with autoclaim mocked
Full test suite passes (73 suites)
Lint, format, and typecheck clean
CI green after cleanup pass
Requires backend PLAPI claim endpoint to be deployed first (CLI gracefully no-ops if endpoint is unavailable)
E2E: clerk init -y → skip auth → verify .env.local and .clerk/keyless.json created → clerk auth login → verify app claimed, linked, and env vars refreshed

changeset-bot · 2026-04-17T17:11:46Z

🦋 Changeset detected

Latest commit: d90fd0a

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 · 2026-04-17T17:11:49Z

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: 49d72fb4-1407-475b-8a10-ef138f3c541a

📥 Commits

Reviewing files that changed from the base of the PR and between 2c93fe4 and d90fd0a.

📒 Files selected for processing (19)

.changeset/auto-claim.md
packages/cli-core/src/commands/auth/README.md
packages/cli-core/src/commands/auth/login.test.ts
packages/cli-core/src/commands/auth/login.ts
packages/cli-core/src/commands/doctor/checks.ts
packages/cli-core/src/commands/doctor/index.ts
packages/cli-core/src/commands/init/README.md
packages/cli-core/src/commands/init/heuristics.ts
packages/cli-core/src/commands/init/index.test.ts
packages/cli-core/src/commands/init/index.ts
packages/cli-core/src/lib/autoclaim.test.ts
packages/cli-core/src/lib/autoclaim.ts
packages/cli-core/src/lib/autolink.ts
packages/cli-core/src/lib/errors.ts
packages/cli-core/src/lib/keyless.test.ts
packages/cli-core/src/lib/keyless.ts
packages/cli-core/src/lib/next-steps.ts
packages/cli-core/src/lib/plapi.ts
packages/cli-core/src/test/lib/stubs.ts

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

.changeset/auto-claim.md
packages/cli-core/src/commands/doctor/index.ts
packages/cli-core/src/lib/keyless.test.ts

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

packages/cli-core/src/lib/errors.ts
packages/cli-core/src/test/lib/stubs.ts
packages/cli-core/src/lib/next-steps.ts
packages/cli-core/src/commands/init/heuristics.ts
packages/cli-core/src/commands/init/index.ts
packages/cli-core/src/commands/init/README.md
packages/cli-core/src/commands/auth/login.ts

📝 Walkthrough

Walkthrough

Adds end-to-end keyless autoclaim: new lib/autoclaim.ts (exports attemptAutoclaim, AutoclaimResult) and lib/keyless.ts (create accountless app, write keys to env, parse claim token, manage .clerk/keyless.json). plapi.ts gains claimApplication. autolink.ts gains linkApp and delegates linking. auth/login invokes autoclaim and routes NEXT_STEPS by claim result. NEXT_STEPS extended. Shared errorMessage helper extracted and reused. Numerous Bun tests and docs updated; init now performs keyless setup and writes temporary keys.

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 26.32% 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 'feat: auto-claim keyless applications on login' directly and concisely describes the main feature addition—automatic claiming of keyless applications upon user login.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, covering the keyless lifecycle, autoclaim orchestration, environment variable handling, and integration points with clear implementation details.
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

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

wyattjoh

Code Review — PR #157

Reviewed with Opus + Codex second-opinion validation.

Blocker

B1. .clerk/keyless.json stores a live claim token with no .gitignore protection(codex confirmed)
packages/cli-core/src/lib/keyless.ts:88-106 writes claimToken under .clerk/ in the user's project. Nothing in this PR (or clerk init today) appends .clerk/ to the project's .gitignore. A developer can git add . and commit the token to a public repo, at which point any third party can claim the app before the original developer logs in, hijacking an app that will later hold production workloads.

Suggestion: in setupKeylessApp or writeKeylessBreadcrumb, append .clerk/ to .gitignore if not already present (mirroring what create-next-app and similar tools do). Add a test that verifies the .gitignore update.

B2. Keyless init writes .env.local but post-claim pull writes the framework default, producing two env files with drifting keys
This is a cross-file interaction with existing code rather than a change in this PR alone, but the PR is where the regression becomes user-visible:

packages/cli-core/src/lib/keyless.ts:57-76 hardcodes const targetFile = join(cwd, ".env.local").
packages/cli-core/src/lib/framework.ts (unchanged) declares envFile: ".env" for Next.js, Astro, and Nuxt.
packages/cli-core/src/commands/env/pull.ts:30-46 (resolveTargetFile) prefers the framework-detected file.

Net effect on a Next.js project: .env.local written at init, .env written by pull after claim, same keys, different values.

Suggestion: use detectEnvFile(cwd) in writeKeysToEnvFile so there is one canonical target. Also update the JSDoc that references .env.local.

B3. Missing changeset
git diff main..HEAD -- .changeset/ is empty. This is a feat: PR touching @clerk/cli-core runtime. The Enforce Changeset workflow will block merge.

Major

M1. App name sent to backend uses basename(cwd).slice(0, 50) with no sanitization(codex confirmed)
packages/cli-core/src/lib/autoclaim.ts:32:

Leaks potentially-sensitive directory names to the Clerk platform API.
.slice(50) truncates on UTF-16 code units; an emoji or non-BMP char at the boundary produces an orphaned surrogate (400 on strict UTF-8 validators).
Backend-invalid chars are not sanitized.

Suggestion: derive the name from package.json#name or the git repo name with basename(cwd) as a fallback, and sanitize + byte-length-truncate before sending.

M2. attemptAutoclaim(cwd) threads cwd but tryPullEnv ignores it
autoclaim.ts:37-50 accepts a cwd argument for the breadcrumb but calls pull({}), which uses process.cwd() internally (pull.ts:53). Today's single call site passes process.cwd() so it is benign, but this is fragile. Either thread cwd through pull options or assert at entry.

M3. createAccountlessApp has no timeout or abort; clerk init hangs on captive portal / slow BAPI(codex confirmed)
packages/cli-core/src/lib/keyless.ts:35-52 and packages/cli-core/src/commands/init/index.ts:272-287: fetch(...) has no AbortController. On slow/broken networks, withSpinner hangs indefinitely. log.debug is only visible with --verbose, so users see nothing.

M4. setupKeylessApp swallows all errors while success copy still renders(codex confirmed)
commands/init/index.ts:270-287 wraps the body in try { ... } catch { log.debug(...) }. Even on filesystem errors, parseClaimToken throws, or the fetch fails, printKeylessInfo still tells the user "Your app is ready with development keys in .env.local". Distinguish expected network failures from unexpected bugs and suppress the success message on failure.

M5. classifyClaimError semantic mismatch and aggressive breadcrumb-clear
autoclaim.ts:62-74 maps 403 to already_claimed, but the message at login.ts:128-132 says "your account does not have an active organization". Name and message disagree; rename the status (e.g. no_organization). Also, 404 unconditionally clears the breadcrumb; a transient DNS blip that returns 404 would destroy the retry signal.

Minor

readKeylessBreadcrumb (keyless.ts:108-119) has no schema validation; a malformed-but-JSON file yields {claimToken: undefined} and autoclaim.ts:33 will POST {token: undefined}.
parseClaimToken uses https://placeholder.com as the synthetic URL base (keyless.ts:81-87); prefer https://example.invalid (RFC 6761).
Em-dashes added in login.ts:130-131,163 and autoclaim.ts:7 (global style rule).
handleAutoclaim prints log.success then log.warn then outro (login.ts:117-124,135-148); noisy ordering.
No retry for 5xx / 429 despite the design claim that "transient failures preserve breadcrumb for retry on next login" (autoclaim.ts:28-36); a short in-process retry with backoff would save users a manual re-login.

Nits

CLAIM_WARNINGS could be an explicit object-literal map of the three warning statuses.
log.info("Environment variables written to .env.local") will be wrong once B2 is fixed.
Test expect(parsed.name).toBeTruthy() (autoclaim.test.ts:164) is too loose; assert the exact truncation.
CI refactor (composite action, workflow_call) is bundled into a feat: PR; splitting would simplify bisect.

Positives

AutoclaimResult discriminated union is cleanly typed and enables exhaustive handling in loginNextSteps. attemptAutoclaim never throws (the type system enforces it). linkApp extraction in autolink.ts is a good refactor. Test coverage for the orchestrator is thorough: all status paths, breadcrumb clear/preserve semantics, env-pull success/failure, linkApp invocation, and request body shape.

B1: add .clerk/ to .gitignore in writeKeylessBreadcrumb to prevent claim token from being committed to public repos B2: use detectEnvFile(cwd) in writeKeysToEnvFile so init and claim write to the same env file (e.g. .env for Next.js, not .env.local) B3: add changeset (minor) for the autoclaim feature M1: derive app name from package.json#name with basename fallback; byte-length-truncate to 50 to avoid surrogate issues M2: thread cwd through tryPullEnv -> pull() instead of relying on process.cwd() internally M3: add 15s AbortController timeout to createAccountlessApp to prevent hanging on captive portal / slow BAPI M4: move printKeylessInfo() inside try block so success copy is suppressed on failure M5: rename already_claimed -> no_organization to match the actual 403 semantic (no active organization); fix em-dashes in messages nit: use https://example.invalid instead of https://placeholder.com nit: add schema validation to readKeylessBreadcrumb nit: tighten autoclaim test name assertion (exact value, not truthy) nit: add gitignore idempotency test + wrong-shape breadcrumb test docs(changeset): Automatically claim and link keyless applications on clerk auth login

wyattjoh

Code review

Substantial new surface (keyless.ts, autoclaim.ts) plus a clean plapi.ts refactor. Core design — discriminated AutoclaimResult, never-throws contract, breadcrumb-preserve-on-transient — is sound. A handful of issues worth tightening before merge: one user-facing inaccuracy (.env.local message), one misleading API parameter (pull({ cwd })), and a few error-handling edges (retry loops, corrupted breadcrumb recovery, silent keyless creation failures).

B1: add .clerk/ to .gitignore in writeKeylessBreadcrumb to prevent claim token from being committed to public repos B2: use detectEnvFile(cwd) in writeKeysToEnvFile so init and claim write to the same env file (e.g. .env for Next.js, not .env.local) B3: add changeset (minor) for the autoclaim feature M1: derive app name from package.json#name with basename fallback; byte-length-truncate to 50 to avoid surrogate issues M2: thread cwd through tryPullEnv -> pull() instead of relying on process.cwd() internally M3: add 15s AbortController timeout to createAccountlessApp to prevent hanging on captive portal / slow BAPI M4: move printKeylessInfo() inside try block so success copy is suppressed on failure M5: rename already_claimed -> no_organization to match the actual 403 semantic (no active organization); fix em-dashes in messages nit: use https://example.invalid instead of https://placeholder.com nit: add schema validation to readKeylessBreadcrumb nit: tighten autoclaim test name assertion (exact value, not truthy) nit: add gitignore idempotency test + wrong-shape breadcrumb test docs(changeset): Automatically claim and link keyless applications on clerk auth login

HIGH: - printKeylessInfo now accepts envFile param so Next.js/Astro/Nuxt users see the correct file name (.env) instead of hardcoded .env.local - drop cwd option from EnvPullOptions — resolveAppContext internally uses process.cwd() so a partial cwd thread is misleading; only caller passes process.cwd() already MEDIUM: - broaden terminal 4xx: all 4xx except 408/429 clear breadcrumb to prevent infinite retry loops on 400/409/422 responses - readKeylessBreadcrumb now clears corrupted/wrong-shape breadcrumb files so the user can recover via re-running clerk init - setupKeylessApp escalates creation failure from log.debug to log.warn with recovery hint (clerk auth login + clerk link) - createAccountlessApp throws BapiError instead of plain Error to match project error-handling protocol LOW: - remove unused AUTOCLAIM_FAILED error code - switch to char-based truncation (Array.from) for app name — simpler than byte-slice and matches likely backend char semantics - add RFC 6761 comment on example.invalid sentinel in parseClaimToken Tests: add 400/429 terminal/retryable tests; verify wrong-shape breadcrumb is cleared from disk; update BapiError assertion

B1: add .clerk/ to .gitignore in writeKeylessBreadcrumb to prevent claim token from being committed to public repos B2: use detectEnvFile(cwd) in writeKeysToEnvFile so init and claim write to the same env file (e.g. .env for Next.js, not .env.local) B3: add changeset (minor) for the autoclaim feature M1: derive app name from package.json#name with basename fallback; byte-length-truncate to 50 to avoid surrogate issues M2: thread cwd through tryPullEnv -> pull() instead of relying on process.cwd() internally M3: add 15s AbortController timeout to createAccountlessApp to prevent hanging on captive portal / slow BAPI M4: move printKeylessInfo() inside try block so success copy is suppressed on failure M5: rename already_claimed -> no_organization to match the actual 403 semantic (no active organization); fix em-dashes in messages nit: use https://example.invalid instead of https://placeholder.com nit: add schema validation to readKeylessBreadcrumb nit: tighten autoclaim test name assertion (exact value, not truthy) nit: add gitignore idempotency test + wrong-shape breadcrumb test docs(changeset): Automatically claim and link keyless applications on clerk auth login

HIGH: - printKeylessInfo now accepts envFile param so Next.js/Astro/Nuxt users see the correct file name (.env) instead of hardcoded .env.local - drop cwd option from EnvPullOptions — resolveAppContext internally uses process.cwd() so a partial cwd thread is misleading; only caller passes process.cwd() already MEDIUM: - broaden terminal 4xx: all 4xx except 408/429 clear breadcrumb to prevent infinite retry loops on 400/409/422 responses - readKeylessBreadcrumb now clears corrupted/wrong-shape breadcrumb files so the user can recover via re-running clerk init - setupKeylessApp escalates creation failure from log.debug to log.warn with recovery hint (clerk auth login + clerk link) - createAccountlessApp throws BapiError instead of plain Error to match project error-handling protocol LOW: - remove unused AUTOCLAIM_FAILED error code - switch to char-based truncation (Array.from) for app name — simpler than byte-slice and matches likely backend char semantics - add RFC 6761 comment on example.invalid sentinel in parseClaimToken Tests: add 400/429 terminal/retryable tests; verify wrong-shape breadcrumb is cleared from disk; update BapiError assertion

wyattjoh

Solid feature overall. The main concerns are an existing-session path that bypasses auto-claim entirely, a raw fetch() call that skips the project's loggedFetch wrapper, a success-log UX wart where both a success line and a Run env pull manually warn can print together, and an overly broad 4xx-is-terminal classifier. See inline comments.

B1: add .clerk/ to .gitignore in writeKeylessBreadcrumb to prevent claim token from being committed to public repos B2: use detectEnvFile(cwd) in writeKeysToEnvFile so init and claim write to the same env file (e.g. .env for Next.js, not .env.local) B3: add changeset (minor) for the autoclaim feature M1: derive app name from package.json#name with basename fallback; byte-length-truncate to 50 to avoid surrogate issues M2: thread cwd through tryPullEnv -> pull() instead of relying on process.cwd() internally M3: add 15s AbortController timeout to createAccountlessApp to prevent hanging on captive portal / slow BAPI M4: move printKeylessInfo() inside try block so success copy is suppressed on failure M5: rename already_claimed -> no_organization to match the actual 403 semantic (no active organization); fix em-dashes in messages nit: use https://example.invalid instead of https://placeholder.com nit: add schema validation to readKeylessBreadcrumb nit: tighten autoclaim test name assertion (exact value, not truthy) nit: add gitignore idempotency test + wrong-shape breadcrumb test docs(changeset): Automatically claim and link keyless applications on clerk auth login

HIGH: - printKeylessInfo now accepts envFile param so Next.js/Astro/Nuxt users see the correct file name (.env) instead of hardcoded .env.local - drop cwd option from EnvPullOptions — resolveAppContext internally uses process.cwd() so a partial cwd thread is misleading; only caller passes process.cwd() already MEDIUM: - broaden terminal 4xx: all 4xx except 408/429 clear breadcrumb to prevent infinite retry loops on 400/409/422 responses - readKeylessBreadcrumb now clears corrupted/wrong-shape breadcrumb files so the user can recover via re-running clerk init - setupKeylessApp escalates creation failure from log.debug to log.warn with recovery hint (clerk auth login + clerk link) - createAccountlessApp throws BapiError instead of plain Error to match project error-handling protocol LOW: - remove unused AUTOCLAIM_FAILED error code - switch to char-based truncation (Array.from) for app name — simpler than byte-slice and matches likely backend char semantics - add RFC 6761 comment on example.invalid sentinel in parseClaimToken Tests: add 400/429 terminal/retryable tests; verify wrong-shape breadcrumb is cleared from disk; update BapiError assertion

- Run autoclaim on agent-mode existing-session path (not just post-OAuth) - Use loggedFetch in createAccountlessApp (bapi tag; verbose shows URL+body) - Drop duplicate log.warn for failed env pull (next-steps already covers it) - Narrow 4xx terminal classification to explicit 404/403 only; all other errors preserve the breadcrumb for retry on next login - Use Intl.Segmenter for grapheme-safe name truncation - Update init/README.md and auth/README.md with keyless API endpoints and breadcrumb lifecycle docs

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/keyless.ts`:
- Around line 117-126: The writeKeylessBreadcrumb function currently writes the
breadcrumb file before ensuring the .gitignore entry, risking an unignored
secret if the process fails; change the order or add cleanup: call
ensureGitignoreEntry(cwd, BREADCRUMB_DIR + "/") before writing the file, then
create the directory and write the breadcrumb to breadcrumbPath(cwd);
alternatively, if you prefer to keep the current order, wrap the
Bun.write(breadcrumbPath(cwd), ...) call in try/catch and on any failure remove
the partial file (using breadcrumbPath(cwd)) so no unignored token remains.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6f39bbd3-a4c1-4dae-b020-21d3ad603374

📥 Commits

Reviewing files that changed from the base of the PR and between 55ea73e and da939c9.

📒 Files selected for processing (18)

.changeset/auto-claim.md
packages/cli-core/src/commands/auth/README.md
packages/cli-core/src/commands/auth/login.test.ts
packages/cli-core/src/commands/auth/login.ts
packages/cli-core/src/commands/doctor/checks.ts
packages/cli-core/src/commands/doctor/index.ts
packages/cli-core/src/commands/init/README.md
packages/cli-core/src/commands/init/heuristics.ts
packages/cli-core/src/commands/init/index.ts
packages/cli-core/src/lib/autoclaim.test.ts
packages/cli-core/src/lib/autoclaim.ts
packages/cli-core/src/lib/autolink.ts
packages/cli-core/src/lib/errors.ts
packages/cli-core/src/lib/keyless.test.ts
packages/cli-core/src/lib/keyless.ts
packages/cli-core/src/lib/next-steps.ts
packages/cli-core/src/lib/plapi.ts
packages/cli-core/src/test/lib/stubs.ts

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

.changeset/auto-claim.md
packages/cli-core/src/commands/auth/login.test.ts
packages/cli-core/src/commands/init/README.md
packages/cli-core/src/commands/auth/login.ts

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

packages/cli-core/src/lib/errors.ts
packages/cli-core/src/lib/plapi.ts
packages/cli-core/src/lib/next-steps.ts
packages/cli-core/src/commands/init/heuristics.ts
packages/cli-core/src/lib/autoclaim.test.ts
packages/cli-core/src/lib/autoclaim.ts
packages/cli-core/src/commands/init/index.ts
packages/cli-core/src/lib/keyless.test.ts