Repository navigation
An agent's clerk init can replace a project's Clerk keys with a new, empty app's keys #556
Description
What happens
When an AI coding agent runs clerk init in a project while signed in to Clerk, the CLI tries to match the project's publishable key to an app in the signed-in account. If nothing matches, it creates a new Clerk app and writes that app's keys into the project's env file, replacing the Clerk keys that were there.
That's correct when the project has no Clerk keys, or only placeholder text like your_key_here. It's wrong when the project already holds a real app's keys that the CLI failed to match.
Who hits it
It needs an AI agent (or a script with no terminal) running clerk init while signed in, in a project using Next.js, Astro, Nuxt, TanStack Start, or React Router. On other frameworks it happens only when the agent passes --login. A person running clerk init in a terminal gets a list of apps to choose from instead, so isn't affected.
The CLI fails to match real keys in three situations:
- The keys belong to an app in a different Clerk account. For example, a project copied from a colleague or a previous job, or a template that came with working keys.
- The project has a secret key but no publishable key the CLI reads. For example, a Next.js project whose env file holds only
CLERK_SECRET_KEY. The CLI matches apps by publishable key only. - The publishable key is stored under a name the framework doesn't read. For example,
CLERK_PUBLISHABLE_KEYin a Next.js project, which reads onlyNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
What the person experiences
clerk initreports success. Nothing says keys were replaced.- A new, empty app appears in their Clerk Dashboard.
- Their project now runs against that empty app. Existing users can't sign in, and the old app's settings (sign-in methods, social login providers) are missing.
- Nothing is deleted in Clerk. The original app and its users still exist. Recovering means putting the old keys back, from the Dashboard of the account that owns the app, or from a backup or git history of the env file. If the keys came from someone else's account, the person may need that owner's help.
How big a deal it is
- How often: unknown. No usage data separates an
initthat created an app over existing keys from one in an empty project. It's probably uncommon, because it needs an agent, a signed-in session, and one of the three situations above. - How bad when it happens: high for that person. It's silent, it breaks sign-in for their app's existing users, and fixing it needs keys they may not have at hand.
- Does it block them: no.
initfinishes, and the damage shows up later, when sign-in fails. - How we know: from reading the code. Not reproduced end to end.
Proposed fix
This changes what agent runs get today, so the clerk init owner should agree to it first.
- Create a new app only when the project holds no real Clerk key. Placeholder text doesn't count.
- Otherwise, stop with a message that names the key and its file, and says to pass
--app <id>or remove the keys. In situation 3, name both variable names: "CLERK_PUBLISHABLE_KEYin.env.localisn't read by Next.js, which readsNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY. Rename it, or pass --app ." - Count only keys in env files, not keys exported in the shell. Otherwise a developer with a Clerk key exported globally would have
initblocked in every new Next.js project. - The tradeoff: an agent setting up a copied project that still holds old keys gets a stop instead of a fresh app.
Where it goes: the agent's create-an-app path in link() (packages/cli-core/src/commands/link/index.ts), which clerk init reaches through the createIfMissing option. It needs a check for real keys that ignores placeholders.
Tests
- In each of the three situations, an agent's
clerk initcreates no app and leaves the env file unchanged. - A project holding only placeholders still gets a new app.
- A Clerk key exported in the shell doesn't block
initin a new Next.js project.
Reproduce
- In a Next.js project, put keys that match no app in your account in
.env.local, for exampleNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_ZmFrZS5leGFtcGxlLmNvbSQandCLERK_SECRET_KEY=sk_test_fake. - Sign in with
clerk auth login, and leave the project unlinked. - Run
CLERK_MODE=agent clerk init --yes. - A new app named after the project folder appears in your account, and
.env.localnow holds its keys.
Activity