@stackframe/stack-cli 2.8.86 → 2.8.88

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import * as fs from "fs";
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync } from "fs";
+import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
 import { fileURLToPath } from "url";
 import * as path from "path";
 import { dirname, join, resolve } from "path";
@@ -11,9 +11,14 @@ import { homedir } from "os";
 import { detectImportPackageFromDir, renderConfigFileContent } from "@stackframe/stack-shared/dist/config-rendering";
 import { checkbox, confirm, input, select } from "@inquirer/prompts";
 import { ALL_APPS } from "@stackframe/stack-shared/dist/apps/apps-config";
+import { createInitPrompt } from "@stackframe/stack-shared/dist/helpers/init-prompt";
 import { query } from "@anthropic-ai/claude-agent-sdk";
-import * as readline from "readline";
-import { execFileSync, spawn } from "child_process";
+import { throwErr } from "@stackframe/stack-shared/dist/utils/errors";
+import { execFileSync, execSync, spawn } from "child_process";
+import extract from "extract-zip";
+import { createInterface } from "readline";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
 
 //#region src/lib/errors.ts
 var CliError = class extends Error {
@@ -208,11 +213,16 @@ function registerExecCommand(program) {
 
 //#endregion
 //#region src/commands/config-file.ts
+const SHOW_ONBOARDING_STACK_CONFIG_VALUE = "show-onboarding";
 function isConfigOverride(value) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
 	const prototype = Object.getPrototypeOf(value);
 	return prototype === Object.prototype || prototype === null;
 }
+function parseConfigOverride(value) {
+	if (value === SHOW_ONBOARDING_STACK_CONFIG_VALUE) return {};
+	return isConfigOverride(value) ? value : null;
+}
 function parseGitHubRepository() {
 	const repository = process.env.GITHUB_REPOSITORY;
 	if (!repository) return null;
@@ -288,8 +298,8 @@ function registerConfigCommand(program) {
 		if (ext !== ".js" && ext !== ".ts") throw new CliError("Config file must have a .js or .ts extension.");
 		if (!fs.existsSync(filePath)) throw new CliError(`Config file not found: ${filePath}`);
 		const { createJiti } = await import("jiti");
-		const config = (await createJiti(import.meta.url).import(filePath)).config;
-		if (!isConfigOverride(config)) throw new CliError(`Config file must export a plain \`config\` object. Example: import type { StackConfig } from "${detectImportPackageFromDir(path.dirname(filePath)) ?? "@stackframe/js"}"; export const config: StackConfig = { ... };`);
+		const config = parseConfigOverride((await createJiti(import.meta.url).import(filePath)).config);
+		if (config == null) throw new CliError(`Config file must export a plain \`config\` object or "show-onboarding". Example: import type { StackConfig } from "${detectImportPackageFromDir(path.dirname(filePath)) ?? "@stackframe/js"}"; export const config: StackConfig = { ... };`);
 		const source = buildConfigPushSource(opts.configFile);
 		if (isProjectAuthWithSecretServerKey(auth)) await pushConfigWithSecretServerKey(auth, config, source);
 		else {
@@ -307,131 +317,24 @@ function isNonInteractiveEnv() {
 }
 
 //#endregion
-//#region src/lib/init-prompt.ts
-const createInitPrompt = (web, configPath) => `=============================
-STACK AUTH SETUP INSTRUCTIONS
-=============================
-
-These instructions describe how to set up Stack Auth.
-${web ? `
-First of all, if you have access to a terminal, it is better to use the \`npx @stackframe/stack-cli init\`` : ""}
-
-Install mcp server from https://mcp.stack-auth.com if not already installed
-
-For reference, questions, or information on Stack Auth, you can query the docs on https://docs.stack-auth.com via curl or any tools that you have
-
-## Setup
-
-### 1) Install the package
-
-Run the install command using whatever package manager the project uses (npm, yarn, pnpm, bun):
-
-| Framework | Package |
-|-----------|---------|
-| Next.js | \`@stackframe/stack\` |
-| React | \`@stackframe/react\` |
-| Vanilla JS | \`@stackframe/js\` |
-
-### 2) Create the Stack apps
-
-Depending on whether you're on a client or a server, you will want to create stackClientApp or stackServerApp. Some environments, like Next.js, have both, so create both files.
-
-The stack client app has client-level permissions. It contains most of the useful methods and hooks for your client-side code.
-The stack server app has full read and write access to all users. It requires STACK_SECRET_SERVER_KEY env variable and should only be used in secure context
-
-In Next.js, env vars are auto-detected (NEXT_PUBLIC_STACK_PROJECT_ID etc.), so the constructor needs no explicit config. For other frameworks, you must pass projectId explicitly using the framework's env var access method. Pass publishableClientKey only if your project is configured to require publishable client keys.
-
-The tokenStore should be "nextjs-cookie" for Next.js, or "cookie" for all other frameworks.
-
-Make sure to set redirectMethod on non next.js frameworks. For example for tanstack router import like so:
-import { useNavigate } from '@tanstack/react-router'
-
-\`\`\`ts
-// src/stack/client.ts
-import { StackClientApp } from "@stackframe/stack"; // or "@stackframe/react" or "@stackframe/js"
-
-export const stackClientApp = new StackClientApp({
-  // Next.js: omit projectId/publishableClientKey (auto-detected from NEXT_PUBLIC_ env vars)
-  // Other frameworks: pass projectId explicitly, and publishableClientKey only if required by your project. For Vite:
-  //   projectId: import.meta.env.VITE_STACK_PROJECT_ID,
-  //   publishableClientKey: import.meta.env.VITE_STACK_PUBLISHABLE_CLIENT_KEY,
-  tokenStore: "nextjs-cookie", // or "cookie" for non-Next.js,
-  // redirectMethod: { useNavigate } // or "window"
-});
-\`\`\`
-
-If the framework has server-side support (e.g. Next.js), also create a server app:
-
-\`\`\`ts
-// src/stack/server.ts
-import "server-only";
-import { StackServerApp } from "@stackframe/stack";
-import { stackClientApp } from "./client";
-
-export const stackServerApp = new StackServerApp({
-  inheritsFrom: stackClientApp,
-});
-\`\`\`
-
-### 3) Create the Stack handler (if available in framework)
-
-This sets up pages for sign in, sign up, password reset, etc.
-
-\`\`\`tsx
-import { StackHandler } from "@stackframe/stack"; // Next.js
-// import { StackHandler } from "@stackframe/react"; // React
-
-export default function Handler() {
-  return <StackHandler fullPage />;
-}
-\`\`\`
-
-### 4) Create a Suspense boundary
-
-Suspense is necessary for many stack auth hooks such as useUser to function. Add a loading component with a custom loading indicator for the current project. Don't add if one already exists
-
-For example:
-\`\`\`tsx
-//src/loading.tsx
-
-export default function Loading() {
-  return <p>Loading...</p>
+//#region src/lib/create-project.ts
+async function createProjectInteractively(user, opts = {}) {
+	let displayName = opts.displayName;
+	if (!displayName) {
+		if (isNonInteractiveEnv()) throw new CliError("--display-name is required in non-interactive environments (CI).");
+		displayName = await input({
+			message: "Project display name:",
+			default: opts.defaultDisplayName,
+			validate: (v) => v.trim().length > 0 || "Display name cannot be empty."
+		});
+	}
+	const teams = await user.listTeams();
+	if (teams.length === 0) throw new CliError("No teams found on your account. Create a team at app.stack-auth.com first.");
+	return await user.createProject({
+		displayName: displayName.trim(),
+		teamId: teams[0].id
+	});
 }
-\`\`\`
-
-### 5) Link environment variables
-
-This is only necessary if not using local emulator. Ensure these are ignored by git.
-
-Rename the env var keys in .env to match the framework's convention for client-exposed variables. For example, Vite requires VITE_ prefix, Next.js uses NEXT_PUBLIC_, etc. The values should stay the same — only rename the keys.
-
-The required variables are:
-- Project ID (e.g. NEXT_PUBLIC_STACK_PROJECT_ID, VITE_STACK_PROJECT_ID, etc.)
-- Secret server key: STACK_SECRET_SERVER_KEY (only for frameworks with server-side support, no prefix needed)
-
-The publishable client key (e.g. NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY, VITE_STACK_PUBLISHABLE_CLIENT_KEY, etc.) is only required if your project has publishable client keys enabled as a requirement.
-
-### 6) React only: Wrap the entire page in a Stack provider
-
-This is used for the useUser and useStackApp hooks.
-
-\`\`\`tsx
-import { StackProvider, StackTheme } from "@stackframe/stack";
-import { stackClientApp } from "../stack/client"; // adjust relative path
-\`\`\`
-
-Then wrap the body content: 
-
-\`\`\`tsx
-return (
-  <body>
-    <StackProvider app={stackClientApp}>
-      <StackTheme>{children}</StackTheme>
-    </StackProvider>
-  </body>
-);
-\`\`\`
-`;
 
 //#endregion
 //#region src/lib/claude-agent.ts
@@ -589,7 +492,7 @@ async function runClaudeAgent(options) {
 //#endregion
 //#region src/commands/init.ts
 function registerInitCommand(program) {
-	program.command("init").description("Initialize Stack Auth in your project").option("--mode <mode>", "Mode: create, link-config, or link-cloud (skips interactive prompts)").option("--apps <apps>", "Comma-separated app IDs to enable (for create mode)").option("--config-file <path>", "Path to existing config file (for link-config mode)").option("--select-project-id <id>", "Project ID to link (for link-cloud mode)").option("--output-dir <dir>", "Directory to write output files (defaults to cwd)").option("--no-agent", "Skip Claude agent and print setup instructions instead").action(async (opts) => {
+	program.command("init").description("Initialize Stack Auth in your project").option("--mode <mode>", "Mode: create, create-cloud, link-config, or link-cloud (skips interactive prompts)").option("--apps <apps>", "Comma-separated app IDs to enable (for create mode)").option("--config-file <path>", "Path to existing config file (for link-config mode)").option("--select-project-id <id>", "Project ID to link (for link-cloud mode)").option("--output-dir <dir>", "Directory to write output files (defaults to cwd)").option("--no-agent", "Skip Claude agent and print setup instructions instead").action(async (opts) => {
 		if (!(opts.mode != null) && isNonInteractiveEnv()) throw new CliError("stack init requires an interactive terminal. Use --mode flag for non-interactive usage.");
 		try {
 			await runInit(program, opts);
@@ -602,15 +505,71 @@ function registerInitCommand(program) {
 		}
 	});
 }
+function validateOptions(opts) {
+	if (opts.selectProjectId && opts.configFile) throw new CliError("--select-project-id and --config-file cannot be used together.");
+	const incompatible = {
+		"create": ["selectProjectId", "configFile"],
+		"create-cloud": [
+			"selectProjectId",
+			"configFile",
+			"apps"
+		],
+		"link-config": ["selectProjectId", "apps"],
+		"link-cloud": ["configFile", "apps"]
+	};
+	const flagNames = {
+		selectProjectId: "--select-project-id",
+		configFile: "--config-file",
+		apps: "--apps"
+	};
+	if (opts.mode) {
+		for (const key of incompatible[opts.mode]) if (opts[key] != null) throw new CliError(`${flagNames[key]} cannot be used with --mode ${opts.mode}.`);
+	}
+}
 async function runInit(program, opts) {
 	const flags = program.opts();
 	const outputDir = opts.outputDir ? path.resolve(opts.outputDir) : process.cwd();
+	if (!fs.existsSync(outputDir)) throw new CliError(`Output directory does not exist: ${outputDir}`);
+	validateOptions(opts);
 	console.log("Welcome to Stack Auth!\n");
-	const mode = "link";
+	let mode;
+	if (opts.mode) mode = opts.mode;
+	else if (opts.selectProjectId) mode = "link-cloud";
+	else if (opts.configFile) mode = "link-config";
+	else if (await select({
+		message: "Would you like to link to an existing project, or create a new one?",
+		choices: [{
+			name: "Create a new project",
+			value: "create"
+		}, {
+			name: "Link an existing project",
+			value: "link"
+		}]
+	}) === "link") mode = "link";
+	else mode = await select({
+		message: "Where would you like to create the project?",
+		choices: [{
+			name: "Stack Auth Cloud",
+			value: "hosted"
+		}, {
+			name: "Local (requires local emulator installation, ~1.3gb storage required)",
+			value: "local"
+		}]
+	}) === "local" ? "create" : "create-cloud";
 	let configPath;
-	if (mode === "link" || mode === "link-config" || mode === "link-cloud") configPath = (await handleLink(flags, opts, outputDir)).configPath;
-	else if (mode === "create") configPath = (await handleCreate(opts, outputDir)).configPath;
-	else throw new CliError(`Unknown mode: ${mode}`);
+	switch (mode) {
+		case "link":
+		case "link-config":
+		case "link-cloud":
+			configPath = (await handleLink(flags, opts, outputDir, mode)).configPath;
+			break;
+		case "create":
+			configPath = (await handleCreate(opts, outputDir)).configPath;
+			break;
+		case "create-cloud":
+			configPath = (await handleCreateCloud(flags, opts, outputDir)).configPath;
+			break;
+	}
 	const initPrompt = createInitPrompt(false, configPath);
 	if (opts.agent !== false && !isNonInteractiveEnv()) {
 		if (!await runClaudeAgent({
@@ -622,11 +581,20 @@ async function runInit(program, opts) {
 		}
 	} else console.log("\n" + initPrompt);
 }
-async function handleLink(flags, opts, outputDir) {
+async function handleLink(flags, opts, outputDir, resolvedMode) {
 	let source;
-	if (opts.mode === "link-config") source = "config-file";
-	else if (opts.mode === "link-cloud") source = "cloud";
-	else source = "cloud";
+	if (resolvedMode === "link-config") source = "config-file";
+	else if (resolvedMode === "link-cloud") source = "cloud";
+	else source = await select({
+		message: "How would you like to link your project?",
+		choices: [{
+			name: "Link from config file",
+			value: "config-file"
+		}, {
+			name: "Link from app.stack-auth.com",
+			value: "cloud"
+		}]
+	});
 	if (source === "config-file") return await handleLinkFromConfigFile(opts);
 	return await handleLinkFromCloud(flags, opts, outputDir);
 }
@@ -644,43 +612,34 @@ async function handleLinkFromConfigFile(opts) {
 	console.log(`\nLinked to config file: ${configPath}`);
 	return { configPath };
 }
-async function handleLinkFromCloud(flags, opts, outputDir) {
-	let sessionAuth;
+async function ensureLoggedInSession(flags) {
 	try {
-		sessionAuth = resolveSessionAuth(flags);
+		return resolveSessionAuth(flags);
 	} catch (e) {
 		if (e instanceof AuthError) {
 			if (isNonInteractiveEnv()) throw new CliError("Not logged in. Run `stack login` first or set STACK_CLI_REFRESH_TOKEN.");
 			console.log("You need to log in first.\n");
 			await performLogin(flags);
-			sessionAuth = resolveSessionAuth(flags);
-		} else throw e;
+			return resolveSessionAuth(flags);
+		}
+		throw e;
 	}
-	const projects = await (await getInternalUser(sessionAuth)).listOwnedProjects();
-	if (projects.length === 0) throw new CliError("You don't own any projects. Create one at app.stack-auth.com first.");
-	let projectId;
-	if (opts.selectProjectId) {
-		if (!projects.find((p) => p.id === opts.selectProjectId)) throw new CliError(`Project '${opts.selectProjectId}' not found among your owned projects.`);
-		projectId = opts.selectProjectId;
-	} else projectId = await select({
-		message: "Select a project:",
-		choices: projects.map((p) => ({
-			name: `${p.displayName} (${p.id})`,
-			value: p.id
-		}))
-	});
-	const apiKey = await projects.find((p) => p.id === projectId).app.createInternalApiKey({
+}
+async function writeProjectKeysToEnv(project, outputDir) {
+	const apiKey = await project.app.createInternalApiKey({
 		description: "Created by CLI init script",
 		expiresAt: new Date(Date.now() + 1e3 * 60 * 60 * 24 * 365 * 200),
 		hasPublishableClientKey: true,
 		hasSecretServerKey: true,
 		hasSuperSecretAdminKey: false
 	});
+	const publishableClientKey = apiKey.publishableClientKey ?? throwErr("createInternalApiKey returned no publishableClientKey despite hasPublishableClientKey=true");
+	const secretServerKey = apiKey.secretServerKey ?? throwErr("createInternalApiKey returned no secretServerKey despite hasSecretServerKey=true");
 	const envLines = [
 		"# Stack Auth",
-		`NEXT_PUBLIC_STACK_PROJECT_ID=${projectId}`,
-		`NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=${apiKey.publishableClientKey ?? ""}`,
-		`STACK_SECRET_SERVER_KEY=${apiKey.secretServerKey ?? ""}`
+		`NEXT_PUBLIC_STACK_PROJECT_ID=${project.id}`,
+		`NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=${publishableClientKey}`,
+		`STACK_SECRET_SERVER_KEY=${secretServerKey}`
 	].join("\n");
 	const envPath = path.resolve(outputDir, ".env");
 	if (fs.existsSync(envPath)) {
@@ -702,6 +661,41 @@ async function handleLinkFromCloud(flags, opts, outputDir) {
 		fs.writeFileSync(envPath, envLines + "\n");
 		console.log("\nCreated .env with Stack Auth keys");
 	}
+}
+async function handleCreateCloud(flags, opts, outputDir) {
+	const newProject = await createProjectInteractively(await getInternalUser(await ensureLoggedInSession(flags)), { defaultDisplayName: path.basename(outputDir) });
+	console.log(`\nCreated project: ${newProject.displayName} (${newProject.id})\n`);
+	await writeProjectKeysToEnv(newProject, outputDir);
+	return {};
+}
+async function handleLinkFromCloud(flags, opts, outputDir) {
+	const user = await getInternalUser(await ensureLoggedInSession(flags));
+	let projects = await user.listOwnedProjects();
+	let autoCreatedProjectId = null;
+	if (projects.length === 0) {
+		if (isNonInteractiveEnv()) throw new CliError("No projects found. Run `stack project create --display-name <name>` first, or set --select-project-id.");
+		if (!await confirm({
+			message: "You don't have any Stack Auth projects yet. Would you like to create one?",
+			default: true
+		})) throw new CliError("You don't own any projects. Create one at app.stack-auth.com or re-run and choose to create one.");
+		const newProject = await createProjectInteractively(user, { defaultDisplayName: path.basename(outputDir) });
+		console.log(`\nCreated project: ${newProject.displayName} (${newProject.id})\n`);
+		projects = [newProject];
+		autoCreatedProjectId = newProject.id;
+	}
+	let projectId;
+	if (opts.selectProjectId) {
+		if (!projects.find((p) => p.id === opts.selectProjectId)) throw new CliError(`Project '${opts.selectProjectId}' not found among your owned projects.`);
+		projectId = opts.selectProjectId;
+	} else if (autoCreatedProjectId) projectId = autoCreatedProjectId;
+	else projectId = await select({
+		message: "Select a project:",
+		choices: projects.map((p) => ({
+			name: `${p.displayName} (${p.id})`,
+			value: p.id
+		}))
+	});
+	await writeProjectKeysToEnv(projects.find((p) => p.id === projectId), outputDir);
 	return {};
 }
 async function performLogin(flags) {
@@ -744,6 +738,16 @@ async function handleCreate(opts, outputDir) {
 	}
 	const content = renderConfigFileContent({ apps: { installed: Object.fromEntries(selectedApps.map((appId) => [appId, { enabled: true }])) } }, detectImportPackageFromDir(path.dirname(configPath)));
 	fs.mkdirSync(path.dirname(configPath), { recursive: true });
+	if (fs.existsSync(configPath)) {
+		if (isNonInteractiveEnv()) throw new CliError(`Config file already exists at ${configPath}. Refusing to overwrite in non-interactive mode.`);
+		if (!await confirm({
+			message: `Config file already exists at ${configPath}. Overwrite?`,
+			default: false
+		})) {
+			console.log("\nLeaving existing config file unchanged.");
+			return { configPath };
+		}
+	}
 	fs.writeFileSync(configPath, content);
 	console.log(`\nConfig file written to ${configPath}`);
 	return { configPath };
@@ -751,18 +755,6 @@ async function handleCreate(opts, outputDir) {
 
 //#endregion
 //#region src/commands/project.ts
-function prompt(question) {
-	const rl = readline.createInterface({
-		input: process.stdin,
-		output: process.stdout
-	});
-	return new Promise((resolve) => {
-		rl.question(question, (answer) => {
-			rl.close();
-			resolve(answer);
-		});
-	});
-}
 function registerProjectCommand(program) {
 	const project = program.command("project").description("Manage projects");
 	project.command("list").description("List your owned projects").action(async () => {
@@ -780,19 +772,7 @@ function registerProjectCommand(program) {
 		}
 	});
 	project.command("create").description("Create a new project").option("--display-name <name>", "Project display name").action(async (opts) => {
-		const user = await getInternalUser(resolveSessionAuth(program.opts()));
-		let displayName = opts.displayName;
-		if (!displayName) {
-			if (isNonInteractiveEnv()) throw new CliError("--display-name is required in non-interactive environments (CI).");
-			displayName = await prompt("Project display name: ");
-			if (!displayName.trim()) throw new CliError("Display name cannot be empty.");
-		}
-		const teams = await user.listTeams();
-		if (teams.length === 0) throw new CliError("No teams found. You need a team to create a project.");
-		const newProject = await user.createProject({
-			displayName,
-			teamId: teams[0].id
-		});
+		const newProject = await createProjectInteractively(await getInternalUser(resolveSessionAuth(program.opts())), { displayName: opts.displayName });
 		if (program.opts().json) console.log(JSON.stringify({
 			id: newProject.id,
 			displayName: newProject.displayName
@@ -801,16 +781,296 @@ function registerProjectCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/lib/iso.ts
+const SECTOR = 2048;
+function bothEndian32(n) {
+	const b = Buffer.alloc(8);
+	b.writeUInt32LE(n, 0);
+	b.writeUInt32BE(n, 4);
+	return b;
+}
+function bothEndian16(n) {
+	const b = Buffer.alloc(4);
+	b.writeUInt16LE(n, 0);
+	b.writeUInt16BE(n, 2);
+	return b;
+}
+function padString(s, len, fill = " ") {
+	const buf = Buffer.alloc(len, fill.charCodeAt(0));
+	buf.write(s.slice(0, len), 0, "ascii");
+	return buf;
+}
+function ucs2BE(s) {
+	const buf = Buffer.alloc(s.length * 2);
+	for (let i = 0; i < s.length; i++) buf.writeUInt16BE(s.charCodeAt(i), i * 2);
+	return buf;
+}
+function padUcs2BE(s, byteLen) {
+	const buf = Buffer.alloc(byteLen);
+	const wholeChars = Math.floor(byteLen / 2);
+	for (let i = 0; i < wholeChars; i++) buf.writeUInt16BE(i < s.length ? s.charCodeAt(i) : 32, i * 2);
+	if (byteLen % 2 === 1) buf[byteLen - 1] = 32;
+	return buf;
+}
+function dirRecordingDate(d) {
+	const buf = Buffer.alloc(7);
+	buf[0] = d.getUTCFullYear() - 1900;
+	buf[1] = d.getUTCMonth() + 1;
+	buf[2] = d.getUTCDate();
+	buf[3] = d.getUTCHours();
+	buf[4] = d.getUTCMinutes();
+	buf[5] = d.getUTCSeconds();
+	buf[6] = 0;
+	return buf;
+}
+function volumeDate(d) {
+	const pad = (n, w) => String(n).padStart(w, "0");
+	const s = pad(d.getUTCFullYear(), 4) + pad(d.getUTCMonth() + 1, 2) + pad(d.getUTCDate(), 2) + pad(d.getUTCHours(), 2) + pad(d.getUTCMinutes(), 2) + pad(d.getUTCSeconds(), 2) + "00";
+	const buf = Buffer.alloc(17);
+	buf.write(s, 0, 16, "ascii");
+	buf[16] = 0;
+	return buf;
+}
+const UNUSED_VOLUME_DATE = (() => {
+	const buf = Buffer.alloc(17, "0".charCodeAt(0));
+	buf[16] = 0;
+	return buf;
+})();
+function isoFileIdentifier(name) {
+	const upper = name.toUpperCase();
+	return Buffer.from(`${upper};1`, "ascii");
+}
+function buildDirRecord(extentSector, dataLength, isDir, recDate, idBytes) {
+	const lenFi = idBytes.length;
+	const pad = lenFi % 2 === 0 ? 1 : 0;
+	const lenDr = 33 + lenFi + pad;
+	const buf = Buffer.alloc(lenDr);
+	buf[0] = lenDr;
+	buf[1] = 0;
+	bothEndian32(extentSector).copy(buf, 2);
+	bothEndian32(dataLength).copy(buf, 10);
+	recDate.copy(buf, 18);
+	buf[25] = isDir ? 2 : 0;
+	buf[26] = 0;
+	buf[27] = 0;
+	bothEndian16(1).copy(buf, 28);
+	buf[32] = lenFi;
+	idBytes.copy(buf, 33);
+	return buf;
+}
+function buildRootDirEntries(rootSector, rootSize, recDate, files) {
+	const records = [];
+	records.push(buildDirRecord(rootSector, rootSize, true, recDate, Buffer.from([0])));
+	records.push(buildDirRecord(rootSector, rootSize, true, recDate, Buffer.from([1])));
+	for (const f of files) records.push(buildDirRecord(f.sector, f.size, false, recDate, f.idBytes));
+	const sectors = [];
+	let current = Buffer.alloc(0);
+	for (const r of records) {
+		if (current.length + r.length > SECTOR) {
+			sectors.push(Buffer.concat([current, Buffer.alloc(SECTOR - current.length)]));
+			current = Buffer.alloc(0);
+		}
+		current = Buffer.concat([current, r]);
+	}
+	if (current.length > 0) sectors.push(Buffer.concat([current, Buffer.alloc(SECTOR - current.length)]));
+	return Buffer.concat(sectors);
+}
+function buildPathTable(rootSector, byteOrder) {
+	const buf = Buffer.alloc(10);
+	buf[0] = 1;
+	buf[1] = 0;
+	if (byteOrder === "LE") {
+		buf.writeUInt32LE(rootSector, 2);
+		buf.writeUInt16LE(1, 6);
+	} else {
+		buf.writeUInt32BE(rootSector, 2);
+		buf.writeUInt16BE(1, 6);
+	}
+	buf[8] = 0;
+	buf[9] = 0;
+	return buf;
+}
+function padToSector(buf) {
+	const rem = buf.length % SECTOR;
+	if (rem === 0) return buf;
+	return Buffer.concat([buf, Buffer.alloc(SECTOR - rem)]);
+}
+function buildVolumeDescriptor(opts) {
+	const buf = Buffer.alloc(SECTOR);
+	buf[0] = opts.joliet ? 2 : 1;
+	buf.write("CD001", 1, 5, "ascii");
+	buf[6] = 1;
+	buf[7] = 0;
+	if (opts.joliet) padUcs2BE("", 32).copy(buf, 8);
+	else padString("", 32).copy(buf, 8);
+	if (opts.joliet) padUcs2BE(opts.volumeId, 32).copy(buf, 40);
+	else padString(opts.volumeId, 32).copy(buf, 40);
+	bothEndian32(opts.volumeSpaceSize).copy(buf, 80);
+	if (opts.joliet) {
+		buf[88] = 37;
+		buf[89] = 47;
+		buf[90] = 69;
+	}
+	bothEndian16(1).copy(buf, 120);
+	bothEndian16(1).copy(buf, 124);
+	bothEndian16(SECTOR).copy(buf, 128);
+	bothEndian32(opts.pathTableSize).copy(buf, 132);
+	buf.writeUInt32LE(opts.lPathSector, 140);
+	buf.writeUInt32LE(0, 144);
+	buf.writeUInt32BE(opts.mPathSector, 148);
+	buf.writeUInt32BE(0, 152);
+	opts.rootDirRecord.copy(buf, 156);
+	const padFn = opts.joliet ? (s, n) => padUcs2BE(s, n) : (s, n) => padString(s, n);
+	padFn("", 128).copy(buf, 190);
+	padFn("", 128).copy(buf, 318);
+	padFn("", 128).copy(buf, 446);
+	padFn("", 128).copy(buf, 574);
+	padFn("", 37).copy(buf, 702);
+	padFn("", 37).copy(buf, 739);
+	padFn("", 37).copy(buf, 776);
+	opts.date.copy(buf, 813);
+	opts.date.copy(buf, 830);
+	UNUSED_VOLUME_DATE.copy(buf, 847);
+	UNUSED_VOLUME_DATE.copy(buf, 864);
+	buf[881] = 1;
+	return buf;
+}
+function buildVolumeDescriptorTerminator() {
+	const buf = Buffer.alloc(SECTOR);
+	buf[0] = 255;
+	buf.write("CD001", 1, 5, "ascii");
+	buf[6] = 1;
+	return buf;
+}
+function buildIso(volumeId, files) {
+	const date = /* @__PURE__ */ new Date();
+	const recDate = dirRecordingDate(date);
+	const volDateBuf = volumeDate(date);
+	const isoEntries = files.map((f) => ({
+		file: f,
+		idBytes: isoFileIdentifier(f.name)
+	}));
+	const jolietEntries = files.map((f) => ({
+		file: f,
+		idBytes: ucs2BE(f.name)
+	}));
+	const dirRecLen = (lenFi) => 33 + lenFi + (lenFi % 2 === 0 ? 1 : 0);
+	const isoRootSize = 68 + isoEntries.reduce((acc, e) => acc + dirRecLen(e.idBytes.length), 0);
+	const jolietRootSize = 68 + jolietEntries.reduce((acc, e) => acc + dirRecLen(e.idBytes.length), 0);
+	if (isoRootSize > SECTOR || jolietRootSize > SECTOR) throw new Error(`Root directory exceeds ${SECTOR} bytes; multi-sector root not supported.`);
+	const sysAreaSectors = 16;
+	const isoLPathSector = sysAreaSectors + 1 + 1 + 1;
+	const isoMPathSector = isoLPathSector + 1;
+	const jolietLPathSector = isoMPathSector + 1;
+	const jolietMPathSector = jolietLPathSector + 1;
+	const isoRootSector = jolietMPathSector + 1;
+	const jolietRootSector = isoRootSector + 1;
+	let nextSector = jolietRootSector + 1;
+	const fileLayout = files.map((f) => {
+		const sector = nextSector;
+		const sectors = Math.max(1, Math.ceil(f.data.length / SECTOR));
+		nextSector += sectors;
+		return {
+			file: f,
+			sector,
+			size: f.data.length
+		};
+	});
+	const totalSectors = nextSector;
+	const pathTableSize = 10;
+	const rootIdent = Buffer.from([0]);
+	const isoRootDirRecordVD = buildDirRecord(isoRootSector, SECTOR, true, recDate, rootIdent);
+	const jolietRootDirRecordVD = buildDirRecord(jolietRootSector, SECTOR, true, recDate, rootIdent);
+	const pvd = buildVolumeDescriptor({
+		joliet: false,
+		volumeId,
+		volumeSpaceSize: totalSectors,
+		pathTableSize,
+		lPathSector: isoLPathSector,
+		mPathSector: isoMPathSector,
+		rootDirRecord: isoRootDirRecordVD,
+		date: volDateBuf
+	});
+	const svd = buildVolumeDescriptor({
+		joliet: true,
+		volumeId,
+		volumeSpaceSize: totalSectors,
+		pathTableSize,
+		lPathSector: jolietLPathSector,
+		mPathSector: jolietMPathSector,
+		rootDirRecord: jolietRootDirRecordVD,
+		date: volDateBuf
+	});
+	const term = buildVolumeDescriptorTerminator();
+	const isoLPath = padToSector(buildPathTable(isoRootSector, "LE"));
+	const isoMPath = padToSector(buildPathTable(isoRootSector, "BE"));
+	const jolietLPath = padToSector(buildPathTable(jolietRootSector, "LE"));
+	const jolietMPath = padToSector(buildPathTable(jolietRootSector, "BE"));
+	const isoRoot = buildRootDirEntries(isoRootSector, SECTOR, recDate, isoEntries.map((e, i) => ({
+		idBytes: e.idBytes,
+		sector: fileLayout[i].sector,
+		size: fileLayout[i].size
+	})));
+	const jolietRoot = buildRootDirEntries(jolietRootSector, SECTOR, recDate, jolietEntries.map((e, i) => ({
+		idBytes: e.idBytes,
+		sector: fileLayout[i].sector,
+		size: fileLayout[i].size
+	})));
+	const fileBuffers = fileLayout.map((f) => {
+		const reservedBytes = Math.max(1, Math.ceil(f.file.data.length / SECTOR)) * SECTOR;
+		if (f.file.data.length === reservedBytes) return f.file.data;
+		const out = Buffer.alloc(reservedBytes);
+		f.file.data.copy(out, 0);
+		return out;
+	});
+	return Buffer.concat([
+		Buffer.alloc(sysAreaSectors * SECTOR),
+		pvd,
+		svd,
+		term,
+		isoLPath,
+		isoMPath,
+		jolietLPath,
+		jolietMPath,
+		isoRoot,
+		jolietRoot,
+		...fileBuffers
+	]);
+}
+function writeIso(path, volumeId, files) {
+	writeFileSync(path, buildIso(volumeId, files));
+}
+
 //#endregion
 //#region src/commands/emulator.ts
 const DEFAULT_EMULATOR_BACKEND_PORT = 26701;
-function emulatorBackendPort() {
-	const raw = process.env.EMULATOR_BACKEND_PORT;
-	if (!raw) return DEFAULT_EMULATOR_BACKEND_PORT;
+const DEFAULT_EMULATOR_DASHBOARD_PORT = 26700;
+const DEFAULT_EMULATOR_MINIO_PORT = 26702;
+const DEFAULT_EMULATOR_INBUCKET_PORT = 26703;
+const DEFAULT_EMULATOR_MOCK_OAUTH_PORT = 26704;
+const DEFAULT_PORT_PREFIX = "81";
+const GITHUB_API = "https://api.github.com";
+const DEFAULT_REPO = "stack-auth/stack-auth";
+const AARCH64_FIRMWARE_PATHS = [
+	"/opt/homebrew/share/qemu/edk2-aarch64-code.fd",
+	"/usr/share/qemu/edk2-aarch64-code.fd",
+	"/usr/share/AAVMF/AAVMF_CODE.fd",
+	"/usr/share/qemu-efi-aarch64/QEMU_EFI.fd"
+];
+function envPort(name, fallback) {
+	const raw = process.env[name];
+	if (!raw) return fallback;
 	const parsed = Number(raw);
-	if (!Number.isInteger(parsed) || parsed <= 0) throw new CliError(`Invalid EMULATOR_BACKEND_PORT: ${raw}`);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new CliError(`Invalid ${name}: ${raw}`);
 	return parsed;
 }
+function emulatorDashboardPort() {
+	return envPort("EMULATOR_DASHBOARD_PORT", DEFAULT_EMULATOR_DASHBOARD_PORT);
+}
+function emulatorBackendPort() {
+	return envPort("EMULATOR_BACKEND_PORT", DEFAULT_EMULATOR_BACKEND_PORT);
+}
 function emulatorHome() {
 	return process.env.STACK_EMULATOR_HOME ?? join(homedir(), ".stack", "emulator");
 }
@@ -826,11 +1086,13 @@ function internalPckPath() {
 async function readInternalPck(timeoutMs = 6e4) {
 	const path = internalPckPath();
 	const deadline = Date.now() + timeoutMs;
-	let delay = 250;
+	let delay = 50;
 	while (Date.now() < deadline) {
-		if (existsSync(path)) {
+		try {
 			const contents = readFileSync(path, "utf-8").trim();
 			if (contents) return contents;
+		} catch (e) {
+			if (e.code !== "ENOENT") throw e;
 		}
 		await new Promise((r) => setTimeout(r, delay));
 		delay = Math.min(delay * 2, 2e3);
@@ -851,35 +1113,96 @@ async function fetchEmulatorCredentials(pck, backendPort, configFile) {
 	});
 	if (!res.ok) throw new CliError(`Failed to initialize local emulator project (${res.status}): ${await res.text()}`);
 	const data = await res.json();
+	if (typeof data.project_id !== "string" || typeof data.publishable_client_key !== "string" || typeof data.secret_server_key !== "string" || typeof data.onboarding_status !== "string" || typeof data.onboarding_outstanding !== "boolean") throw new CliError("Local emulator project endpoint returned an invalid credentials response.");
 	return {
 		project_id: data.project_id,
 		publishable_client_key: data.publishable_client_key,
-		secret_server_key: data.secret_server_key
+		secret_server_key: data.secret_server_key,
+		onboarding_status: data.onboarding_status,
+		onboarding_outstanding: data.onboarding_outstanding
 	};
 }
-function gh(args) {
+function localEmulatorDashboardBaseUrl() {
+	const explicit = process.env.STACK_LOCAL_EMULATOR_DASHBOARD_URL;
+	if (explicit && explicit.trim().length > 0) return explicit.replace(/\/$/, "");
+	return `http://localhost:${emulatorDashboardPort()}`;
+}
+function openUrlInBrowser(url) {
+	try {
+		if (process.platform === "darwin") {
+			execFileSync("open", [url], { stdio: "ignore" });
+			return true;
+		}
+		if (process.platform === "win32") {
+			execFileSync("cmd", [
+				"/c",
+				"start",
+				"",
+				url
+			], { stdio: "ignore" });
+			return true;
+		}
+		execFileSync("xdg-open", [url], { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+function maybeOpenOnboardingPage(credentials) {
+	if (!credentials.onboarding_outstanding) return;
+	const url = `${localEmulatorDashboardBaseUrl()}/new-project?project_id=${encodeURIComponent(credentials.project_id)}`;
+	if (openUrlInBrowser(url)) console.log(`Onboarding is still pending for project ${credentials.project_id}. Opened: ${url}`);
+	else console.warn(`Onboarding is still pending for project ${credentials.project_id}. Open this URL manually: ${url}`);
+}
+function githubToken() {
+	if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
 	try {
-		return execFileSync("gh", args, {
+		return execFileSync("gh", ["auth", "token"], {
 			encoding: "utf-8",
 			stdio: [
 				"pipe",
 				"pipe",
 				"pipe"
 			]
-		}).trim();
-	} catch (err) {
-		if (err instanceof Error && "stderr" in err && typeof err.stderr === "string") throw new CliError(`GitHub CLI error: ${err.stderr}`);
-		throw new CliError("GitHub CLI (gh) is required. Install: https://cli.github.com/");
+		}).trim() || void 0;
+	} catch {
+		return;
+	}
+}
+async function ghApi(path) {
+	const token = githubToken();
+	const headers = {
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28"
+	};
+	if (token) headers.Authorization = `Bearer ${token}`;
+	const res = await fetch(`${GITHUB_API}${path}`, { headers });
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		const hint = res.status === 401 || res.status === 403 ? " (set GITHUB_TOKEN or run `gh auth login` for higher rate limits / private access)" : "";
+		throw new CliError(`GitHub API ${res.status} ${res.statusText} for ${path}${hint}${body ? `: ${body.slice(0, 300)}` : ""}`);
 	}
+	return await res.json();
 }
 function emulatorScriptsDir() {
 	const here = dirname(fileURLToPath(import.meta.url));
 	const bundled = join(here, "emulator");
-	if (existsSync(join(bundled, "run-emulator.sh"))) return bundled;
+	if (existsSync(join(bundled, "run-emulator.sh"))) return ensureExecutable(bundled);
 	const repo = resolve(here, "../../../docker/local-emulator/qemu");
-	if (existsSync(join(repo, "run-emulator.sh"))) return repo;
+	if (existsSync(join(repo, "run-emulator.sh"))) return ensureExecutable(repo);
 	throw new CliError("Emulator scripts not found in CLI bundle.");
 }
+function ensureExecutable(scriptsDir) {
+	try {
+		chmodSync(join(scriptsDir, "run-emulator.sh"), 493);
+	} catch {}
+	return scriptsDir;
+}
+function baseEnvPath() {
+	const path = resolve(emulatorScriptsDir(), "..", ".env.development");
+	if (!existsSync(path)) throw new CliError(`Emulator base.env not found at ${path}`);
+	return path;
+}
 function emulatorSpawnEnv(extra) {
 	return {
 		...process.env,
@@ -888,6 +1211,34 @@ function emulatorSpawnEnv(extra) {
 		...extra
 	};
 }
+function prepareRuntimeConfigIso() {
+	const vmDir = join(emulatorRunDir(), "vm");
+	mkdirSync(vmDir, { recursive: true });
+	const portPrefix = process.env.PORT_PREFIX ?? process.env.NEXT_PUBLIC_STACK_PORT_PREFIX ?? DEFAULT_PORT_PREFIX;
+	const dashboardPort = envPort("EMULATOR_DASHBOARD_PORT", DEFAULT_EMULATOR_DASHBOARD_PORT);
+	const backendPort = envPort("EMULATOR_BACKEND_PORT", DEFAULT_EMULATOR_BACKEND_PORT);
+	const minioPort = envPort("EMULATOR_MINIO_PORT", DEFAULT_EMULATOR_MINIO_PORT);
+	const inbucketPort = envPort("EMULATOR_INBUCKET_PORT", DEFAULT_EMULATOR_INBUCKET_PORT);
+	const mockOAuthPort = envPort("EMULATOR_MOCK_OAUTH_PORT", DEFAULT_EMULATOR_MOCK_OAUTH_PORT);
+	const runtimeEnv = [
+		`STACK_EMULATOR_PORT_PREFIX=${portPrefix}`,
+		`STACK_EMULATOR_DASHBOARD_HOST_PORT=${dashboardPort}`,
+		`STACK_EMULATOR_BACKEND_HOST_PORT=${backendPort}`,
+		`STACK_EMULATOR_MINIO_HOST_PORT=${minioPort}`,
+		`STACK_EMULATOR_INBUCKET_HOST_PORT=${inbucketPort}`,
+		`STACK_EMULATOR_MOCK_OAUTH_HOST_PORT=${mockOAuthPort}`,
+		`STACK_EMULATOR_VM_DIR_HOST=${vmDir}`,
+		""
+	].join("\n");
+	const baseEnv = readFileSync(baseEnvPath());
+	writeIso(join(vmDir, "runtime-config.iso"), "STACKCFG", [{
+		name: "runtime.env",
+		data: Buffer.from(runtimeEnv, "utf-8")
+	}, {
+		name: "base.env",
+		data: baseEnv
+	}]);
+}
 function runEmulator(action, env) {
 	const scriptsDir = emulatorScriptsDir();
 	mkdirSync(emulatorRunDir(), { recursive: true });
@@ -916,115 +1267,305 @@ function isEmulatorRunning() {
 	}
 }
 async function startEmulator(arch) {
-	mkdirSync(emulatorImageDir(), { recursive: true });
 	if (!existsSync(join(emulatorImageDir(), `stack-emulator-${arch}.qcow2`))) {
 		console.log("No emulator image found. Pulling latest...");
-		pullRelease(arch);
+		await pullRelease(arch);
+		await captureLocalSnapshot(arch);
 	}
-	await runEmulator("start", { EMULATOR_ARCH: arch });
+	prepareRuntimeConfigIso();
+	await runEmulator("start", {
+		EMULATOR_ARCH: arch,
+		STACK_EMULATOR_CLI_WROTE_ISO: "1"
+	});
 }
 function resolveArch(raw) {
 	const arch = raw ?? (process.arch === "arm64" ? "arm64" : process.arch === "x64" ? "amd64" : null);
 	if (arch === "arm64" || arch === "amd64") return arch;
 	throw new CliError(`Invalid architecture: ${raw ?? process.arch}. Expected arm64 or amd64.`);
 }
-function pullRelease(arch, opts = {}) {
-	const repo = opts.repo ?? "stack-auth/stack-auth";
+async function pullRelease(arch, opts = {}) {
+	const repo = opts.repo ?? DEFAULT_REPO;
 	const branch = opts.branch ?? "dev";
 	const tag = opts.tag ?? `emulator-${branch}-latest`;
-	const asset = `stack-emulator-${arch}.qcow2`;
 	const imageDir = emulatorImageDir();
 	mkdirSync(imageDir, { recursive: true });
+	const diskAsset = `stack-emulator-${arch}.qcow2`;
+	const diskMatch = (await ghApi(`/repos/${repo}/releases/tags/${tag}`)).assets.find((a) => a.name === diskAsset);
+	if (!diskMatch) throw new CliError(`Asset ${diskAsset} not found in release ${tag}. Run 'stack emulator list-releases' to see available releases.`);
+	await downloadReleaseAsset(diskMatch, imageDir, diskAsset, githubToken(), tag);
+}
+async function captureLocalSnapshot(arch) {
+	preflightForVmStart("pull", arch);
+	prepareRuntimeConfigIso();
+	console.log("Capturing local snapshot (first-time, ~1-3 min cold boot + capture)...");
+	await runEmulator("capture", { EMULATOR_ARCH: arch });
+}
+async function downloadReleaseAsset(match, imageDir, asset, token, tag) {
 	const dest = join(imageDir, asset);
 	const tmpDest = `${dest}.download`;
 	console.log(`Pulling ${asset} from release ${tag}...`);
+	const headers = { Accept: "application/octet-stream" };
+	if (token) headers.Authorization = `Bearer ${token}`;
 	try {
-		execFileSync("gh", [
-			"release",
-			"download",
-			tag,
-			"--repo",
-			repo,
-			"--pattern",
-			asset,
-			"--output",
-			tmpDest,
-			"--clobber"
-		], { stdio: "inherit" });
+		await downloadWithProgress(match.url, headers, tmpDest, match.size);
 	} catch (err) {
 		if (existsSync(tmpDest)) unlinkSync(tmpDest);
-		throw new CliError(`Failed to download ${asset} from release ${tag}: ${err instanceof Error ? err.message : err}\nRun 'stack emulator list-releases' to see available releases.`);
+		if (err instanceof CliError) throw err;
+		throw new CliError(`Failed to download ${asset} from release ${tag}: ${err instanceof Error ? err.message : err}`);
 	}
 	renameSync(tmpDest, dest);
 	console.log(`Downloaded: ${dest}`);
 }
+async function downloadWithProgress(url, headers, dest, totalBytes) {
+	const res = await fetch(url, {
+		headers,
+		redirect: "follow"
+	});
+	if (!res.ok || !res.body) throw new CliError(`Download failed (${res.status} ${res.statusText}): ${url}`);
+	const total = totalBytes ?? (Number(res.headers.get("content-length")) || 0);
+	const isTty = Boolean(process.stderr.isTTY);
+	const startedAt = Date.now();
+	let downloaded = 0;
+	let lastRender = 0;
+	const render = (final) => {
+		const now = Date.now();
+		if (!final && now - lastRender < 100) return;
+		lastRender = now;
+		const elapsed = Math.max(.001, (now - startedAt) / 1e3);
+		const speed = downloaded / elapsed;
+		const line = renderProgressLine(downloaded, total, speed);
+		if (isTty) process.stderr.write(`\r\x1b[2K${line}`);
+		else if (final) process.stderr.write(`${line}\n`);
+	};
+	const body = Readable.fromWeb(res.body);
+	body.on("data", (chunk) => {
+		downloaded += chunk.byteLength;
+		render(false);
+	});
+	await pipeline(body, createWriteStream(dest));
+	render(true);
+	if (isTty) process.stderr.write("\n");
+}
+function renderProgressLine(downloaded, total, bytesPerSec) {
+	const barWidth = 30;
+	const pct = total > 0 ? Math.min(100, downloaded / total * 100) : 0;
+	const filled = total > 0 ? Math.round(downloaded / total * barWidth) : 0;
+	return `  [${"█".repeat(filled) + "░".repeat(Math.max(0, barWidth - filled))}] ${total > 0 ? `${pct.toFixed(1).padStart(5)}%` : "  ?  "}  ${total > 0 ? `${formatBytes(downloaded)}/${formatBytes(total)}` : formatBytes(downloaded)}  ${`${formatBytes(bytesPerSec)}/s`}${total > 0 && bytesPerSec > 0 ? `  eta ${formatDuration((total - downloaded) / bytesPerSec)}` : ""}`;
+}
+function formatBytes(bytes) {
+	if (!Number.isFinite(bytes) || bytes < 0) return "?";
+	const units = [
+		"B",
+		"KB",
+		"MB",
+		"GB",
+		"TB"
+	];
+	let v = bytes;
+	let i = 0;
+	while (v >= 1024 && i < units.length - 1) {
+		v /= 1024;
+		i++;
+	}
+	return `${v.toFixed(v < 10 && i > 0 ? 1 : 0)} ${units[i]}`;
+}
+function formatDuration(seconds) {
+	if (!Number.isFinite(seconds) || seconds < 0) return "?";
+	const s = Math.round(seconds);
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	const rs = s % 60;
+	if (m < 60) return `${m}m${rs.toString().padStart(2, "0")}s`;
+	return `${Math.floor(m / 60)}h${(m % 60).toString().padStart(2, "0")}m`;
+}
+function commandExists(bin) {
+	try {
+		execFileSync(process.platform === "win32" ? "where" : "which", [bin], { stdio: "pipe" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+function platformInstallHint(linuxPkg, macPkg) {
+	switch (process.platform) {
+		case "darwin": return `brew install ${macPkg}`;
+		case "linux": return `apt install ${linuxPkg} (or your distro's equivalent)`;
+		default: return `install ${macPkg}`;
+	}
+}
+function bin(name, linuxPkg, macPkg) {
+	return {
+		name,
+		linuxPkg,
+		macPkg
+	};
+}
+function installHint(b) {
+	return platformInstallHint(b.linuxPkg, b.macPkg);
+}
+function requireBinaries(commandName, bins) {
+	const missing = bins.filter((b) => !commandExists(b.name));
+	if (missing.length === 0) return;
+	throw new CliError(`\`stack emulator ${commandName}\` requires the following missing binaries:\n${missing.map((b) => `  - ${b.name}  →  ${installHint(b)}`).join("\n")}`);
+}
+function warnIfMissing(commandName, bins) {
+	const missing = bins.filter((b) => !commandExists(b.name));
+	if (missing.length === 0) return;
+	for (const b of missing) console.warn(`[stack emulator ${commandName}] optional dep '${b.name}' missing — feature degraded. Install: ${installHint(b)}`);
+}
+async function confirmPrompt(question) {
+	if (!process.stdin.isTTY) throw new CliError("Cannot prompt for confirmation: stdin is not a TTY. Install the missing dependencies manually and retry.");
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return await new Promise((resolvePromise) => {
+		rl.question(`${question} [y/N] `, (answer) => {
+			rl.close();
+			resolvePromise(/^y(es)?$/i.test(answer.trim()));
+		});
+	});
+}
+async function ensureDepsForPull(arch) {
+	const missingBins = [
+		archSpecificQemuBin(arch),
+		...commonVmBins(),
+		bin("zstd", "zstd", "zstd")
+	].filter((b) => !commandExists(b.name));
+	const firmwareMissing = arch === "arm64" && !aarch64FirmwareAvailable();
+	if (missingBins.length === 0 && !firmwareMissing) return;
+	const platform = process.platform;
+	const linuxHasApt = platform === "linux" && commandExists("apt-get");
+	if (platform !== "darwin" && !linuxHasApt) {
+		preflightForVmStart("pull", arch);
+		return;
+	}
+	if (!process.stdin.isTTY) {
+		preflightForVmStart("pull", arch);
+		return;
+	}
+	console.log("The emulator needs the following dependencies that aren't installed:");
+	for (const b of missingBins) console.log(`  - ${b.name}`);
+	if (firmwareMissing) console.log("  - aarch64 UEFI firmware");
+	console.log();
+	const pkgs = /* @__PURE__ */ new Set();
+	for (const b of missingBins) pkgs.add(platform === "darwin" ? b.macPkg : b.linuxPkg);
+	if (firmwareMissing && platform === "linux") pkgs.add("qemu-efi-aarch64");
+	if (firmwareMissing && platform === "darwin") pkgs.add("qemu");
+	const pkgList = Array.from(pkgs).sort();
+	if (pkgList.length === 0) {
+		preflightForVmStart("pull", arch);
+		return;
+	}
+	const brewMissing = platform === "darwin" && !commandExists("brew");
+	console.log("Proposed install plan:");
+	if (brewMissing) {
+		console.log("  - install Homebrew by running the official installer:");
+		console.log("      /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"");
+		console.log("    (executes remote code from raw.githubusercontent.com — review https://brew.sh if unsure)");
+	}
+	if (platform === "darwin") console.log(`  - brew install ${pkgList.join(" ")}`);
+	else console.log(`  - sudo apt-get update && sudo apt-get install -y ${pkgList.join(" ")}`);
+	console.log();
+	if (!await confirmPrompt("Proceed with install?")) throw new CliError("Dependency install declined. Install the missing packages manually and retry.");
+	if (brewMissing) {
+		console.log("\nInstalling Homebrew...");
+		execSync("/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"", { stdio: "inherit" });
+	}
+	console.log("\nInstalling packages...");
+	if (platform === "darwin") execFileSync(commandExists("brew") ? "brew" : existsSync("/opt/homebrew/bin/brew") ? "/opt/homebrew/bin/brew" : "/usr/local/bin/brew", ["install", ...pkgList], { stdio: "inherit" });
+	else {
+		execFileSync("sudo", ["apt-get", "update"], { stdio: "inherit" });
+		execFileSync("sudo", [
+			"apt-get",
+			"install",
+			"-y",
+			...pkgList
+		], { stdio: "inherit" });
+	}
+	console.log();
+}
+function aarch64FirmwareAvailable() {
+	return AARCH64_FIRMWARE_PATHS.some((p) => existsSync(p));
+}
+function commonVmBins() {
+	return [
+		bin("qemu-img", "qemu-utils", "qemu"),
+		bin("socat", "socat", "socat"),
+		bin("curl", "curl", "curl"),
+		bin("nc", "ncat", "netcat"),
+		bin("lsof", "lsof", "lsof"),
+		bin("openssl", "openssl", "openssl")
+	];
+}
+function archSpecificQemuBin(arch) {
+	if (arch === "arm64") return bin("qemu-system-aarch64", "qemu-system-arm", "qemu");
+	return bin("qemu-system-x86_64", "qemu-system-x86", "qemu");
+}
+function preflightForVmStart(commandName, arch) {
+	requireBinaries(commandName, [archSpecificQemuBin(arch), ...commonVmBins()]);
+	warnIfMissing(commandName, [bin("zstd", "zstd", "zstd")]);
+	if (arch === "arm64" && !aarch64FirmwareAvailable()) throw new CliError(`aarch64 UEFI firmware not found. Looked in:\n${AARCH64_FIRMWARE_PATHS.map((p) => `  - ${p}`).join("\n")}\nInstall: ${platformInstallHint("qemu-efi-aarch64", "qemu")}`);
+}
+async function downloadArtifactByName(repo, runId, name, destDir) {
+	const token = githubToken();
+	if (!token) throw new CliError("Downloading workflow run artifacts requires authentication. Set GITHUB_TOKEN or run `gh auth login`.");
+	const match = (await ghApi(`/repos/${repo}/actions/runs/${runId}/artifacts?per_page=100`)).artifacts.find((a) => a.name === name);
+	if (!match) return false;
+	const zipPath = join(destDir, `${name}.zip`);
+	console.log(`Downloading artifact '${name}' from run ${runId}...`);
+	await downloadWithProgress(`${GITHUB_API}/repos/${repo}/actions/artifacts/${match.id}/zip`, {
+		Accept: "application/vnd.github+json",
+		Authorization: `Bearer ${token}`
+	}, zipPath, match.size_in_bytes);
+	await extract(zipPath, { dir: destDir });
+	unlinkSync(zipPath);
+	return true;
+}
 function registerEmulatorCommand(program) {
 	const emulator = program.command("emulator").description("Manage the QEMU local emulator");
-	emulator.command("pull").description("Download an emulator image from GitHub Releases or a PR build").option("--arch <arch>", "Target architecture (default: current system arch)").option("--branch <branch>", "Release branch (default: dev)").option("--tag <tag>", "Specific release tag (default: latest)").option("--repo <repo>", "GitHub repository (default: stack-auth/stack-auth)").option("--pr <number>", "Pull from a PR's CI artifacts").option("--run <id>", "Pull from a specific workflow run's artifacts").action(async (opts) => {
+	emulator.command("pull").description("Download an emulator image from GitHub Releases or a PR build, then capture a local fast-start snapshot").option("--arch <arch>", "Target architecture (default: current system arch)").option("--branch <branch>", "Release branch (default: dev)").option("--tag <tag>", "Specific release tag (default: latest)").option("--repo <repo>", "GitHub repository (default: stack-auth/stack-auth)").option("--pr <number>", "Pull from a PR's CI artifacts").option("--run <id>", "Pull from a specific workflow run's artifacts").option("--skip-snapshot", "Download only the qcow2; skip the one-time local snapshot capture").action(async (opts) => {
 		const arch = resolveArch(opts.arch);
-		const repo = opts.repo ?? "stack-auth/stack-auth";
+		if (!opts.skipSnapshot) await ensureDepsForPull(arch);
+		const repo = opts.repo ?? DEFAULT_REPO;
 		if (opts.run || opts.pr) {
 			let runId = opts.run;
 			if (!runId) {
 				console.log(`Finding latest successful build for PR #${opts.pr}...`);
-				const { headRefName } = JSON.parse(gh([
-					"pr",
-					"view",
-					opts.pr,
-					"--repo",
-					repo,
-					"--json",
-					"headRefName"
-				]));
-				const runs = JSON.parse(gh([
-					"run",
-					"list",
-					"--repo",
-					repo,
-					"--workflow",
-					"qemu-emulator-build.yaml",
-					"--branch",
-					headRefName,
-					"--status",
-					"success",
-					"--limit",
-					"1",
-					"--json",
-					"databaseId"
-				]));
-				if (runs.length === 0) throw new CliError(`No successful build found for PR #${opts.pr} (branch: ${headRefName}).`);
-				runId = String(runs[0].databaseId);
+				const headRefName = (await ghApi(`/repos/${repo}/pulls/${opts.pr}`)).head.ref;
+				const runs = await ghApi(`/repos/${repo}/actions/workflows/qemu-emulator-build.yaml/runs?branch=${encodeURIComponent(headRefName)}&status=success&per_page=1`);
+				if (runs.workflow_runs.length === 0) throw new CliError(`No successful build found for PR #${opts.pr} (branch: ${headRefName}).`);
+				runId = String(runs.workflow_runs[0].id);
 			}
 			const imageDir = emulatorImageDir();
 			mkdirSync(imageDir, { recursive: true });
 			const dest = join(imageDir, `stack-emulator-${arch}.qcow2`);
+			const snapshotDest = join(imageDir, `stack-emulator-${arch}.savevm.zst`);
+			const snapshotRawDest = join(imageDir, `stack-emulator-${arch}.savevm.raw`);
 			if (existsSync(dest)) unlinkSync(dest);
-			console.log(`Downloading qemu-emulator-${arch} from workflow run ${runId}...`);
-			try {
-				execFileSync("gh", [
-					"run",
-					"download",
-					runId,
-					"--repo",
-					repo,
-					"--name",
-					`qemu-emulator-${arch}`,
-					"--dir",
-					imageDir
-				], { stdio: "inherit" });
-			} catch (err) {
-				throw new CliError(`Failed to download artifact from run ${runId}: ${err instanceof Error ? err.message : err}`);
-			}
+			if (existsSync(snapshotDest)) unlinkSync(snapshotDest);
+			if (existsSync(snapshotRawDest)) unlinkSync(snapshotRawDest);
+			if (!await downloadArtifactByName(repo, runId, `qemu-emulator-${arch}`, imageDir)) throw new CliError(`Artifact qemu-emulator-${arch} not found in workflow run ${runId}.`);
 			if (!existsSync(dest)) throw new CliError(`Expected image not found at ${dest} after download.`);
 			console.log(`Downloaded: ${dest}`);
-		} else pullRelease(arch, {
-			repo,
-			branch: opts.branch,
-			tag: opts.tag
-		});
+		} else {
+			const imageDir = emulatorImageDir();
+			const snapshotDest = join(imageDir, `stack-emulator-${arch}.savevm.zst`);
+			const snapshotRawDest = join(imageDir, `stack-emulator-${arch}.savevm.raw`);
+			if (existsSync(snapshotDest)) unlinkSync(snapshotDest);
+			if (existsSync(snapshotRawDest)) unlinkSync(snapshotRawDest);
+			await pullRelease(arch, {
+				repo,
+				branch: opts.branch,
+				tag: opts.tag
+			});
+		}
+		if (opts.skipSnapshot) console.log("--skip-snapshot: not capturing a local snapshot. First `stack emulator start` will cold-boot.");
+		else await captureLocalSnapshot(arch);
 	});
 	emulator.command("start").description("Start the emulator in the background (auto-pulls the latest image if none exists)").option("--arch <arch>", "Target architecture (default: current system arch). Non-native uses software emulation and is significantly slower.").option("--config-file <path>", "Path to a config file; when set, credentials for this project are printed to stdout as JSON").action(async (opts) => {
 		const arch = resolveArch(opts.arch);
+		preflightForVmStart("start", arch);
 		let resolvedConfigFile;
 		if (opts.configFile) {
 			resolvedConfigFile = resolve(opts.configFile);
@@ -1034,11 +1575,17 @@ function registerEmulatorCommand(program) {
 		else await startEmulator(arch);
 		if (resolvedConfigFile) {
 			const creds = await fetchEmulatorCredentials(await readInternalPck(), emulatorBackendPort(), resolvedConfigFile);
-			console.log(JSON.stringify(creds, null, 2));
+			maybeOpenOnboardingPage(creds);
+			console.log(JSON.stringify({
+				project_id: creds.project_id,
+				publishable_client_key: creds.publishable_client_key,
+				secret_server_key: creds.secret_server_key
+			}, null, 2));
 		}
 	});
 	emulator.command("run").description("Start the emulator, run a command, and stop the emulator when the command exits").argument("<cmd>", "Command to run (e.g. \"npm run dev\")").option("--arch <arch>", "Target architecture").option("--config-file <path>", "Path to a config file; fetches credentials and injects STACK_PROJECT_ID / STACK_PUBLISHABLE_CLIENT_KEY / STACK_SECRET_SERVER_KEY into the child").action(async (cmd, opts) => {
 		const arch = resolveArch(opts.arch);
+		preflightForVmStart("run", arch);
 		let resolvedConfigFile;
 		if (opts.configFile) {
 			resolvedConfigFile = resolve(opts.configFile);
@@ -1052,14 +1599,21 @@ function registerEmulatorCommand(program) {
 			const pck = await readInternalPck();
 			const backendPort = emulatorBackendPort();
 			const creds = await fetchEmulatorCredentials(pck, backendPort, resolvedConfigFile);
+			maybeOpenOnboardingPage(creds);
 			const apiUrl = `http://127.0.0.1:${backendPort}`;
 			childEnv.STACK_PROJECT_ID = creds.project_id;
 			childEnv.NEXT_PUBLIC_STACK_PROJECT_ID = creds.project_id;
+			childEnv.VITE_STACK_PROJECT_ID = creds.project_id;
+			childEnv.EXPO_PUBLIC_STACK_PROJECT_ID = creds.project_id;
 			childEnv.STACK_PUBLISHABLE_CLIENT_KEY = creds.publishable_client_key;
 			childEnv.NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY = creds.publishable_client_key;
+			childEnv.VITE_STACK_PUBLISHABLE_CLIENT_KEY = creds.publishable_client_key;
+			childEnv.EXPO_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY = creds.publishable_client_key;
 			childEnv.STACK_SECRET_SERVER_KEY = creds.secret_server_key;
 			childEnv.STACK_API_URL = apiUrl;
 			childEnv.NEXT_PUBLIC_STACK_API_URL = apiUrl;
+			childEnv.VITE_STACK_API_URL = apiUrl;
+			childEnv.EXPO_PUBLIC_STACK_API_URL = apiUrl;
 		}
 		const child = spawn(cmd, {
 			shell: true,
@@ -1078,24 +1632,34 @@ function registerEmulatorCommand(program) {
 			if (alreadyRunning) process.exit(exitCode);
 			else {
 				console.log("\nStopping emulator...");
-				runEmulator("stop").catch(() => {}).finally(() => process.exit(exitCode));
+				const warnStopFailed = (e) => {
+					const msg = e instanceof Error ? e.message : String(e);
+					process.stderr.write(`Failed to stop emulator cleanly: ${msg}\n`);
+				};
+				runEmulator("stop").catch(warnStopFailed).finally(() => process.exit(exitCode));
 			}
 		});
 	});
-	emulator.command("stop").description("Stop the emulator (data preserved; use 'reset' to clear)").action(() => runEmulator("stop"));
-	emulator.command("reset").description("Reset emulator state for a fresh boot").action(() => runEmulator("reset"));
-	emulator.command("status").description("Show emulator and service health").action(() => runEmulator("status"));
-	emulator.command("list-releases").description("List available emulator releases").option("--repo <repo>", "GitHub repository (default: stack-auth/stack-auth)").action((opts) => {
-		const repo = opts.repo ?? "stack-auth/stack-auth";
+	emulator.command("stop").description("Stop the emulator (data preserved; use 'reset' to clear)").action(() => {
+		requireBinaries("stop", [bin("socat", "socat", "socat")]);
+		return runEmulator("stop");
+	});
+	emulator.command("reset").description("Reset emulator state for a fresh boot").action(() => {
+		requireBinaries("reset", [bin("socat", "socat", "socat")]);
+		return runEmulator("reset");
+	});
+	emulator.command("status").description("Show emulator and service health").action(() => {
+		requireBinaries("status", [bin("curl", "curl", "curl"), bin("nc", "ncat", "netcat")]);
+		return runEmulator("status");
+	});
+	emulator.command("list-releases").description("List available emulator releases").option("--repo <repo>", "GitHub repository (default: stack-auth/stack-auth)").action(async (opts) => {
+		const repo = opts.repo ?? DEFAULT_REPO;
 		console.log(`Available emulator releases from ${repo}:\n`);
-		const lines = gh([
-			"release",
-			"list",
-			"--repo",
-			repo,
-			"--limit",
-			"20"
-		]).split("\n").filter((l) => l.toLowerCase().includes("emulator"));
+		const lines = (await ghApi(`/repos/${repo}/releases?per_page=50`)).filter((r) => (r.tag_name + " " + (r.name ?? "")).toLowerCase().includes("emulator")).slice(0, 20).map((r) => {
+			const status = r.draft ? "Draft" : r.prerelease ? "Pre-release" : "Latest";
+			const date = r.published_at ? r.published_at.slice(0, 10) : "";
+			return `${r.tag_name}\t${status}\t${date}`;
+		});
 		if (lines.length === 0) console.log("No emulator releases found.");
 		else for (const line of lines) console.log(line);
 	});