clerk · rafa-thayto · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026
diff --git a/bun.lock b/bun.lock
diff --git a/package.json b/package.json
@@ -7,6 +7,7 @@
   "scripts": {
     "build": "bun run --filter @clerk/cli-core build",
     "dev": "bun run --cwd packages/cli-core dev",
+    "typecheck": "bun run --filter @clerk/cli-core typecheck",
     "test": "bun run scripts/run-tests.ts --pattern 'packages/cli-core/src/**/*.test.ts' --pattern 'scripts/**/*.test.ts'",
     "test:e2e": "bun run scripts/run-tests.ts --pattern 'test/e2e/*.test.ts' --retries 1",
     "test:e2e:op": "bun run scripts/run-e2e-op.ts",
@@ -37,7 +38,7 @@
     "oxfmt": "^0.36.0",
     "oxlint": "^1.58.0",
     "playwright": "^1.59.1",
-    "typescript": "^5"
+    "typescript": "^6.0.2"
   },
   "nano-staged": {
     "*.{ts,tsx,js,jsx}": [

diff --git a/packages/cli-core/mocks/bun.lock b/packages/cli-core/mocks/bun.lock
diff --git a/packages/cli-core/mocks/package.json b/packages/cli-core/mocks/package.json
@@ -6,7 +6,7 @@
     "dev": "vite"
   },
   "devDependencies": {
-    "typescript": "^5",
+    "typescript": "^6.0.2",
     "vite": "^6.3.5"
   }
 }
diff --git a/packages/cli-core/mocks/src/main.ts b/packages/cli-core/mocks/src/main.ts
@@ -4,9 +4,9 @@ const app = document.getElementById("app")!;
 const params = new URLSearchParams(window.location.search);
 const callbackPort = params.get("callback_port");
 
-type Screen = "sign-in" | "sign-up" | "select-app" | "success-new" | "success-existing";
+type AppScreen = "sign-in" | "sign-up" | "select-app" | "success-new" | "success-existing";
 
-function render(screen: Screen) {
+function render(screen: AppScreen) {
   switch (screen) {
     case "sign-in":
       return renderSignIn();

diff --git a/packages/cli-core/package.json b/packages/cli-core/package.json
@@ -10,6 +10,7 @@
     "build": "bun build ./src/cli.ts --outfile ./dist/cli.js --target node --external @napi-rs/keyring",
     "build:compile": "bun build --compile --no-compile-autoload-dotenv ./src/cli.ts --outfile ./dist/clerk",
     "dev": "bun run ./src/cli.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "oxlint src/",
     "format": "oxfmt --write src/",
     "format:check": "oxfmt --check src/"

diff --git a/packages/cli-core/src/commands/api/catalog.test.ts b/packages/cli-core/src/commands/api/catalog.test.ts
@@ -146,13 +146,17 @@ describe("filterEndpoints", () => {
   test("filters by summary", () => {
     const results = filterEndpoints(catalog, "retrieve");
     expect(results.length).toBe(1);
-    expect(results[0].operationId).toBe("GetUser");
+    const [firstResult] = results;
+    expect(firstResult).toBeDefined();
+    expect(firstResult?.operationId).toBe("GetUser");
   });
 
   test("filters by tag", () => {
     const results = filterEndpoints(catalog, "organizations");
     expect(results.length).toBe(1);
-    expect(results[0].tag).toBe("Organizations");
+    const [firstResult] = results;
+    expect(firstResult).toBeDefined();
+    expect(firstResult?.tag).toBe("Organizations");
   });
 
   test("is case-insensitive", () => {

diff --git a/packages/cli-core/src/commands/api/index.test.ts b/packages/cli-core/src/commands/api/index.test.ts
@@ -9,6 +9,7 @@ import {
   promptsStubs,
   stubFetch,
 } from "../../test/lib/stubs.ts";
+import { getPlapiBaseUrl } from "../../lib/environment.ts";
 
 let mockStoredToken: string | null = null;
 mock.module("../../lib/credential-store.ts", () => ({
@@ -399,8 +400,7 @@ describe("api command", () => {
     });
 
     await runApi("/v1/platform/applications", { platform: true });
-    expect(capturedUrl).toContain("api.clerk.com");
-    expect(capturedUrl).not.toContain("api.clerk.dev");
+    expect(capturedUrl).toStartWith(`${getPlapiBaseUrl()}/`);
     expect(capturedHeaders?.get("Authorization")).toBe("Bearer plat_key_123");
   });
 

diff --git a/packages/cli-core/src/commands/api/interactive.test.ts b/packages/cli-core/src/commands/api/interactive.test.ts
@@ -156,8 +156,10 @@ describe("apiInteractive", () => {
     await apiInteractive({});
 
     expect(fetchCalls.length).toBe(1);
-    expect(fetchCalls[0].url).toContain("/v1/users");
-    expect(fetchCalls[0].method).toBe("GET");
+    const [firstCall] = fetchCalls;
+    expect(firstCall).toBeDefined();
+    expect(firstCall?.url).toContain("/v1/users");
+    expect(firstCall?.method).toBe("GET");
   });
 
   test("prompts for path parameters", async () => {
@@ -180,7 +182,9 @@ describe("apiInteractive", () => {
     await apiInteractive({});
 
     expect(fetchCalls.length).toBe(1);
-    expect(fetchCalls[0].url).toContain("/v1/users/user_abc123");
+    const [firstCall] = fetchCalls;
+    expect(firstCall).toBeDefined();
+    expect(firstCall?.url).toContain("/v1/users/user_abc123");
   });
 
   test("aborts when user declines confirmation", async () => {

diff --git a/packages/cli-core/src/commands/auth/login.test.ts b/packages/cli-core/src/commands/auth/login.test.ts
@@ -335,7 +335,7 @@ describe("login", () => {
 
     expect(
       consoleErrorSpy.mock.calls.some(
-        (c) => typeof c[0] === "string" && (c[0] as string).includes("Next steps:"),
+        (c: unknown[]) => typeof c[0] === "string" && (c[0] as string).includes("Next steps:"),
       ),
     ).toBe(false);
   });

diff --git a/packages/cli-core/src/commands/init/frameworks/astro.test.ts b/packages/cli-core/src/commands/init/frameworks/astro.test.ts
@@ -15,6 +15,7 @@ function makeCtx(overrides?: Partial<ProjectContext>): ProjectContext {
       name: "Astro",
       sdk: "@clerk/astro",
       envVar: "PUBLIC_CLERK_PUBLISHABLE_KEY",
+      envFile: ".env",
     },
     typescript: true,
     srcDir: false,

diff --git a/packages/cli-core/src/commands/init/frameworks/nextjs-app.test.ts b/packages/cli-core/src/commands/init/frameworks/nextjs-app.test.ts
@@ -15,6 +15,7 @@ function makeCtx(overrides?: Partial<ProjectContext>): ProjectContext {
       name: "Next.js",
       sdk: "@clerk/nextjs",
       envVar: "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY",
+      envFile: ".env.local",
     },
     variant: "app-router",
     typescript: true,

diff --git a/packages/cli-core/src/commands/init/frameworks/nextjs-pages.test.ts b/packages/cli-core/src/commands/init/frameworks/nextjs-pages.test.ts
@@ -15,6 +15,7 @@ function makeCtx(overrides?: Partial<ProjectContext>): ProjectContext {
       name: "Next.js",
       sdk: "@clerk/nextjs",
       envVar: "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY",
+      envFile: ".env.local",
     },
     variant: "pages-router",
     typescript: true,

diff --git a/packages/cli-core/src/commands/init/frameworks/nuxt.test.ts b/packages/cli-core/src/commands/init/frameworks/nuxt.test.ts
@@ -15,6 +15,7 @@ function makeCtx(overrides?: Partial<ProjectContext>): ProjectContext {
       name: "Nuxt",
       sdk: "@clerk/nuxt",
       envVar: "NUXT_PUBLIC_CLERK_PUBLISHABLE_KEY",
+      envFile: ".env",
     },
     typescript: true,
     srcDir: false,

diff --git a/packages/cli-core/src/commands/init/frameworks/react-router.test.ts b/packages/cli-core/src/commands/init/frameworks/react-router.test.ts
@@ -15,6 +15,7 @@ function makeCtx(overrides?: Partial<ProjectContext>): ProjectContext {
       name: "React Router",
       sdk: "@clerk/react-router",
       envVar: "VITE_CLERK_PUBLISHABLE_KEY",
+      envFile: ".env",
     },
     typescript: true,
     srcDir: false,

diff --git a/packages/cli-core/src/commands/init/frameworks/react-router.ts b/packages/cli-core/src/commands/init/frameworks/react-router.ts
@@ -226,7 +226,8 @@ function ensureRouteImported(source: string): string {
   const importMatch = source.match(
     /import\s*\{([^}]*)\}\s*from\s*["']@react-router\/dev\/routes["']/,
   );
-  if (!importMatch || /\broute\b/.test(importMatch[1])) return source;
+  const importedNames = importMatch?.[1];
+  if (!importedNames || /\broute\b/.test(importedNames)) return source;
 
   return source.replace(
     /(\bimport\s*\{[^}]*)(\}\s*from\s*["']@react-router\/dev\/routes["'])/,
@@ -302,7 +303,7 @@ function injectRouteEntries(
   const canonicalPattern = /export default \[([^\]]*)\]\s*satisfies\s*RouteConfig\s*;/s;
   const canonical = source.match(canonicalPattern);
   if (canonical) {
-    const innerContent = canonical[1].trimEnd();
+    const innerContent = (canonical[1] ?? "").trimEnd();
     const separator = innerContent.length > 0 && !innerContent.endsWith(",") ? "," : "";
     const newInner = `${innerContent}${separator}\n  ${newEntries},\n`;
     return source.replace(canonicalPattern, `export default [${newInner}] satisfies RouteConfig;`);
@@ -312,7 +313,7 @@ function injectRouteEntries(
   const simplePattern = /(export\s+default\s+\[)([\s\S]*?)(\]\s*;)/;
   const simple = source.match(simplePattern);
   if (simple) {
-    const innerContent = simple[2].trimEnd();
+    const innerContent = (simple[2] ?? "").trimEnd();
     const separator = innerContent.length > 0 && !innerContent.endsWith(",") ? "," : "";
     const newInner = `${innerContent}${separator}\n  ${newEntries},\n`;
     return source.replace(simplePattern, `$1${newInner}$3`);

diff --git a/packages/cli-core/src/commands/init/frameworks/react.test.ts b/packages/cli-core/src/commands/init/frameworks/react.test.ts
@@ -15,6 +15,7 @@ function makeCtx(overrides?: Partial<ProjectContext>): ProjectContext {
       name: "React",
       sdk: "@clerk/react",
       envVar: "VITE_CLERK_PUBLISHABLE_KEY",
+      envFile: ".env",
     },
     typescript: true,
     srcDir: true,

diff --git a/packages/cli-core/src/commands/init/frameworks/tanstack-start.test.ts b/packages/cli-core/src/commands/init/frameworks/tanstack-start.test.ts
@@ -15,6 +15,7 @@ function makeCtx(overrides?: Partial<ProjectContext>): ProjectContext {
       name: "TanStack Start",
       sdk: "@clerk/tanstack-react-start",
       envVar: "VITE_CLERK_PUBLISHABLE_KEY",
+      envFile: ".env",
     },
     typescript: true,
     srcDir: true,

diff --git a/packages/cli-core/src/commands/init/frameworks/transformations.ts b/packages/cli-core/src/commands/init/frameworks/transformations.ts
@@ -81,7 +81,7 @@ export function wrapBodyWithProvider(content: string, provider: string): string
   const providerIndent = bodyIndent + "  ";
   const contentIndent = providerIndent + "  ";
 
-  const trimmedInner = inner.trim();
+  const trimmedInner = (inner ?? "").trim();
   const reindented = trimmedInner
     .split("\n")
     .map((line) => {

diff --git a/packages/cli-core/src/commands/init/frameworks/vue.test.ts b/packages/cli-core/src/commands/init/frameworks/vue.test.ts
@@ -15,6 +15,7 @@ function makeCtx(overrides?: Partial<ProjectContext>): ProjectContext {
       name: "Vue",
       sdk: "@clerk/vue",
       envVar: "VITE_CLERK_PUBLISHABLE_KEY",
+      envFile: ".env",
     },
     typescript: true,
     srcDir: true,

diff --git a/packages/cli-core/src/commands/init/heuristics.ts b/packages/cli-core/src/commands/init/heuristics.ts
@@ -17,6 +17,9 @@ export async function installSdk(ctx: ProjectContext): Promise<void> {
   // the actual binary being installed (e.g. teammate committed bun.lock, you
   // only have npm). Fail fast with a useful message rather than a raw ENOENT.
   const pmBinary = addCmd.split(" ")[0];
+  if (!pmBinary) {
+    throw new Error(`Invalid package manager install command: ${addCmd}`);
+  }
   if (Bun.which(pmBinary) === null) {
     console.log(
       yellow(

diff --git a/packages/cli-core/src/commands/init/index.test.ts b/packages/cli-core/src/commands/init/index.test.ts
@@ -19,14 +19,17 @@ import * as heuristics from "./heuristics.ts";
 import * as skillsMod from "./skills.ts";
 import * as bootstrapMod from "./bootstrap.ts";
 import { init } from "./index.ts";
+import type { FrameworkInfo } from "../../lib/framework.ts";
+import type { ProjectContext } from "./frameworks/types.ts";
 
-const FAKE_CTX = {
+const FAKE_CTX: ProjectContext = {
   cwd: "/tmp/test",
   framework: {
     dep: "react",
     name: "React",
     sdk: "@clerk/react",
     envVar: "VITE_CLERK_PUBLISHABLE_KEY",
+    envFile: ".env",
   },
   typescript: true,
   srcDir: false,
@@ -43,9 +46,11 @@ const FAKE_BOOTSTRAP = {
 };
 
 describe("init", () => {
+  const originalEnv = { ...process.env };
   let spies: ReturnType<typeof spyOn>[];
 
   afterEach(() => {
+    process.env = { ...originalEnv };
     for (const s of spies) s.mockRestore();
   });
 
@@ -95,6 +100,7 @@ describe("init", () => {
   }
 
   test("suppresses auth next-steps when login runs during init", async () => {
+    delete process.env.CLERK_PLATFORM_API_KEY;
     setup({ email: null });
     spyOn(context, "gatherContext").mockResolvedValue(FAKE_CTX);
     spyOn(heuristics, "getAuthenticatedEmail").mockResolvedValue(null);
@@ -173,11 +179,12 @@ describe("init", () => {
   });
 
   test("passes frameworkOverride to bootstrap when provided", async () => {
-    const fwOverride = {
+    const fwOverride: FrameworkInfo = {
       dep: "next",
       name: "Next.js",
       sdk: "@clerk/nextjs",
       envVar: "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY",
+      envFile: ".env",
     };
     setup({ email: "test@test.com" });
     spyOn(frameworkMod, "lookupFramework").mockReturnValue(fwOverride);
@@ -228,15 +235,24 @@ describe("init", () => {
   test("short-circuits env pull and skills install when already set up", async () => {
     const { gatherContextSpy } = setup({ email: "test@test.com" });
 
-    gatherContextSpy.mockResolvedValueOnce({
+    const existingCtx: ProjectContext = {
       cwd: "/tmp/fake",
-      framework: { name: "Next.js", dep: "next", sdk: "@clerk/nextjs", publishableKeyEnv: "x" },
+      framework: {
+        name: "Next.js",
+        dep: "next",
+        sdk: "@clerk/nextjs",
+        envVar: "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY",
+        envFile: ".env",
+      },
       deps: { next: "15.0.0" },
       packageManager: "bun",
       typescript: true,
       srcDir: false,
       existingClerk: true,
-    } as never);
+      envFile: ".env",
+    };
+
+    gatherContextSpy.mockResolvedValueOnce(existingCtx);
 
     await init({ yes: true });
 
@@ -268,7 +284,7 @@ describe("init", () => {
 
     gatherContextSpy.mockResolvedValue(mockCtx);
     spyOn(scaffoldMod, "scaffold").mockResolvedValue({
-      actions: [{ type: "write", path: "app/layout.tsx", content: "" }],
+      actions: [{ type: "modify", path: "app/layout.tsx", content: "", description: "" }],
       postInstructions: [],
     });
 

diff --git a/packages/cli-core/src/commands/init/prompts/index.ts b/packages/cli-core/src/commands/init/prompts/index.ts
@@ -33,7 +33,7 @@ const TEMPLATES = {
 } satisfies Record<string, string>;
 
 type TemplateName = keyof typeof TEMPLATES;
-type FrameworkTemplateName = Exclude<TemplateName, "generic" | "generic-fallback">;
+type FrameworkTemplateName = Exclude<TemplateName, "generic">;
 type FrameworkPromptInfo = { template: FrameworkTemplateName; docsUrl: string };
 
 function loadTemplate(name: TemplateName): string {