@stackframe/stack-cli 2.8.83 → 2.8.84

package/dist/emulator/run-emulator.sh

@@ -0,0 +1,402 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=common.sh
+source "$SCRIPT_DIR/common.sh"
+
+IMAGE_DIR="${EMULATOR_IMAGE_DIR:-$HOME/.stack/emulator/images}"
+RUN_DIR="${EMULATOR_RUN_DIR:-$HOME/.stack/emulator/run}"
+
+VM_RAM="${EMULATOR_RAM:-4096}"
+VM_CPUS="${EMULATOR_CPUS:-4}"
+PORT_PREFIX="${PORT_PREFIX:-${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}}"
+READY_TIMEOUT="${EMULATOR_READY_TIMEOUT:-240}"
+
+# Fixed host-side ports for the QEMU emulator (267xx range).
+# Only user-facing services are exposed; internal deps stay inside the VM.
+EMULATOR_DASHBOARD_PORT="${EMULATOR_DASHBOARD_PORT:-26700}"
+EMULATOR_BACKEND_PORT="${EMULATOR_BACKEND_PORT:-26701}"
+EMULATOR_MINIO_PORT="${EMULATOR_MINIO_PORT:-26702}"
+EMULATOR_INBUCKET_PORT="${EMULATOR_INBUCKET_PORT:-26703}"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+log()  { echo -e "${GREEN}[emulator]${NC} $*"; }
+warn() { echo -e "${YELLOW}[emulator]${NC} $*"; }
+err()  { echo -e "${RED}[emulator]${NC} $*" >&2; }
+info() { echo -e "${CYAN}[emulator]${NC} $*"; }
+
+
+detect_host
+ARCH="${EMULATOR_ARCH:-$HOST_ARCH}"
+
+select_accelerator() {
+  local accel="tcg"
+  if [ "$ARCH" = "$HOST_ARCH" ]; then
+    case "$HOST_OS" in
+      darwin)
+        if "$(qemu_binary_for_arch "$ARCH")" -accel help 2>&1 | grep -q hvf; then
+          accel="hvf"
+        fi
+        ;;
+      linux)
+        if [ -w /dev/kvm ]; then
+          accel="kvm"
+        fi
+        ;;
+    esac
+  fi
+  ACCEL="$accel"
+}
+
+select_accelerator
+
+VM_DIR="$RUN_DIR/vm"
+
+image_path() {
+  echo "$IMAGE_DIR/stack-emulator-$ARCH.qcow2"
+}
+
+runtime_iso_path() {
+  echo "$VM_DIR/runtime-config.iso"
+}
+
+# Returns a fast fingerprint (size:mtime) of the base QEMU image.
+# Used to detect whether the image has changed since the overlay was created.
+base_image_fingerprint() {
+  local img="$1"
+  case "$HOST_OS" in
+    darwin) stat -f "%z:%m" "$img" 2>/dev/null ;;
+    linux)  stat -c "%s:%Y" "$img" 2>/dev/null ;;
+    *)      stat -f "%z:%m" "$img" 2>/dev/null || stat -c "%s:%Y" "$img" 2>/dev/null ;;
+  esac
+}
+
+prepare_runtime_config_iso() {
+  local cfg_dir="$VM_DIR/runtime-config"
+  local cfg_iso
+  cfg_iso="$(runtime_iso_path)"
+  rm -rf "$cfg_dir"
+  mkdir -p "$cfg_dir"
+  {
+    printf "STACK_EMULATOR_PORT_PREFIX=%s\n" "$PORT_PREFIX"
+    printf "STACK_EMULATOR_DASHBOARD_HOST_PORT=%s\n" "$EMULATOR_DASHBOARD_PORT"
+    printf "STACK_EMULATOR_BACKEND_HOST_PORT=%s\n" "$EMULATOR_BACKEND_PORT"
+    printf "STACK_EMULATOR_MINIO_HOST_PORT=%s\n" "$EMULATOR_MINIO_PORT"
+    printf "STACK_EMULATOR_INBUCKET_HOST_PORT=%s\n" "$EMULATOR_INBUCKET_PORT"
+    printf "STACK_EMULATOR_VM_DIR_HOST=%s\n" "$VM_DIR"
+  } > "$cfg_dir/runtime.env"
+  cp "$SCRIPT_DIR/../.env.development" "$cfg_dir/base.env"
+  make_iso_from_dir "$cfg_iso" "STACKCFG" "$cfg_dir"
+}
+
+service_is_up() {
+  local port="$1"
+  local proto="$2"
+  local path="${3:-/}"
+  local expected_codes="${4:-200}"
+
+  if [ "$proto" = "tcp" ]; then
+    nc -z -w2 127.0.0.1 "$port" 2>/dev/null
+    return $?
+  fi
+
+  local code
+  code="$(curl -s -o /dev/null -w "%{http_code}" --max-time 2 "http://127.0.0.1:${port}${path}" 2>/dev/null || true)"
+  local expected
+  for expected in ${expected_codes//,/ }; do
+    if [ "$code" = "$expected" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+deps_ready() {
+  service_is_up "$EMULATOR_MINIO_PORT" http /minio/health/live &&
+    service_is_up "$EMULATOR_INBUCKET_PORT" http /
+}
+
+app_ready() {
+  service_is_up "$EMULATOR_BACKEND_PORT" http "/health?db=1" &&
+    service_is_up "$EMULATOR_DASHBOARD_PORT" http /handler/sign-in
+}
+
+all_ready() {
+  deps_ready && app_ready
+}
+
+wait_for_condition() {
+  local label="$1"
+  local timeout="$2"
+  local check_fn="$3"
+  local started=$SECONDS
+  local elapsed=0
+
+  log "Waiting for ${label}..."
+  while [ "$elapsed" -lt "$timeout" ]; do
+    if "$check_fn"; then
+      echo ""
+      log "${label} ready in ${elapsed}s"
+      return 0
+    fi
+    sleep 1
+    elapsed=$((SECONDS - started))
+    printf "\r  [%3ds] %s..." "$elapsed" "$label"
+  done
+  echo ""
+  return 1
+}
+
+build_qemu_cmd() {
+  local base_img
+  base_img="$(image_path)"
+
+  if [ ! -f "$base_img" ]; then
+    err "Missing QEMU image: $base_img"
+    err "Run docker/local-emulator/qemu/build-image.sh $ARCH first."
+    exit 1
+  fi
+
+  mkdir -p "$VM_DIR"
+  local fingerprint_file="$VM_DIR/base-image.fingerprint"
+  local current_fp
+  current_fp="$(base_image_fingerprint "$base_img")"
+  if [ -f "$VM_DIR/disk.qcow2" ]; then
+    if [ -f "$fingerprint_file" ] && [ "$(cat "$fingerprint_file")" = "$current_fp" ]; then
+      log "Reusing existing overlay disk (changes persist)"
+    else
+      warn "QEMU base image has changed — recreating overlay."
+      rm -f "$VM_DIR/disk.qcow2" "$fingerprint_file"
+    fi
+  fi
+  if [ ! -f "$VM_DIR/disk.qcow2" ]; then
+    qemu-img create -f qcow2 -b "$base_img" -F qcow2 "$VM_DIR/disk.qcow2" >/dev/null
+    base_image_fingerprint "$base_img" > "$fingerprint_file"
+  fi
+
+  local qemu_bin machine cpu firmware_args=()
+  qemu_bin="$(qemu_binary_for_arch "$ARCH")"
+  case "$ARCH" in
+    arm64)
+      machine="virt"
+      cpu="max"
+      local firmware
+      firmware="$(find_aarch64_firmware)"
+      firmware_args=(-bios "$firmware")
+      ;;
+    amd64)
+      machine="q35"
+      if [ "$ACCEL" = "tcg" ] && [ "$HOST_ARCH" != "amd64" ]; then
+        cpu="qemu64"
+      else
+        cpu="max"
+      fi
+      ;;
+  esac
+
+  local netdev="user,id=net0"
+  # Only expose user-facing services; internal deps stay inside the VM.
+  # Bind to 127.0.0.1 so the emulator is not reachable from the LAN.
+  netdev+=",hostfwd=tcp:127.0.0.1:${EMULATOR_DASHBOARD_PORT}-:${PORT_PREFIX}01"
+  netdev+=",hostfwd=tcp:127.0.0.1:${EMULATOR_BACKEND_PORT}-:${PORT_PREFIX}02"
+  netdev+=",hostfwd=tcp:127.0.0.1:${EMULATOR_MINIO_PORT}-:9090"
+  netdev+=",hostfwd=tcp:127.0.0.1:${EMULATOR_INBUCKET_PORT}-:9001"
+  # Mock OAuth server: browser redirects land on `localhost:${PORT_PREFIX}14`
+  # (backend sets STACK_OAUTH_MOCK_URL to that value), so we forward host:port
+  # ↔ VM:port on the same number. Collides with pnpm dev, but the two modes
+  # are mutually exclusive.
+  netdev+=",hostfwd=tcp:127.0.0.1:${PORT_PREFIX}14-:${PORT_PREFIX}14"
+
+  QEMU_CMD=(
+    "$qemu_bin"
+    -machine "$machine"
+    -accel "$ACCEL"
+    -cpu "$cpu"
+    "${firmware_args[@]}"
+    -boot order=c
+    -m "$VM_RAM"
+    -smp "$VM_CPUS"
+    -drive "file=$VM_DIR/disk.qcow2,format=qcow2,if=virtio"
+    -drive "file=$(runtime_iso_path),format=raw,if=virtio,readonly=on"
+    -netdev "$netdev"
+    -device virtio-net-pci,netdev=net0
+    -device virtio-balloon-pci
+    -virtfs "local,path=/,mount_tag=hostfs,security_model=none"
+    -chardev "socket,id=monitor,path=$VM_DIR/monitor.sock,server=on,wait=off"
+    -mon "chardev=monitor,mode=control"
+    -serial "file:$VM_DIR/serial.log"
+    -display none
+    -daemonize
+    -pidfile "$VM_DIR/qemu.pid"
+  )
+
+}
+
+is_running() {
+  if [ ! -f "$VM_DIR/qemu.pid" ]; then
+    return 1
+  fi
+  local pid
+  pid="$(cat "$VM_DIR/qemu.pid")"
+  kill -0 "$pid" 2>/dev/null
+}
+
+tail_vm_logs() {
+  if [ -f "$VM_DIR/serial.log" ]; then
+    echo ""
+    warn "Last serial log lines:"
+    tail -40 "$VM_DIR/serial.log" || true
+  fi
+}
+
+ensure_ports_free() {
+  local ports=("$EMULATOR_DASHBOARD_PORT" "$EMULATOR_BACKEND_PORT" "$EMULATOR_MINIO_PORT" "$EMULATOR_INBUCKET_PORT" "${PORT_PREFIX}14")
+  local port
+  for port in "${ports[@]}"; do
+    if lsof -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then
+      err "Port $port is already in use. Stop any conflicting services first."
+      exit 1
+    fi
+  done
+}
+
+start_vm() {
+  mkdir -p "$VM_DIR"
+  : > "$VM_DIR/serial.log"
+  prepare_runtime_config_iso
+  build_qemu_cmd
+  "${QEMU_CMD[@]}"
+}
+
+stop_vm() {
+  if [ ! -f "$VM_DIR/qemu.pid" ]; then
+    return 0
+  fi
+  local pid
+  pid="$(cat "$VM_DIR/qemu.pid")"
+  if kill -0 "$pid" 2>/dev/null; then
+    if [ -S "$VM_DIR/monitor.sock" ]; then
+      echo '{"execute":"qmp_capabilities"}' | socat - UNIX-CONNECT:"$VM_DIR/monitor.sock" >/dev/null 2>&1 || true
+      echo '{"execute":"system_powerdown"}' | socat - UNIX-CONNECT:"$VM_DIR/monitor.sock" >/dev/null 2>&1 || true
+      sleep 3
+    fi
+    if kill -0 "$pid" 2>/dev/null; then
+      kill "$pid" 2>/dev/null || true
+      sleep 1
+      kill -9 "$pid" 2>/dev/null || true
+    fi
+  fi
+  rm -f "$VM_DIR/qemu.pid" "$VM_DIR/monitor.sock" "$VM_DIR/serial.log"
+  rm -rf "$VM_DIR/runtime-config"
+  rm -f "$VM_DIR/runtime-config.iso"
+}
+
+cmd_start() {
+  ensure_ports_free
+  mkdir -p "$RUN_DIR"
+
+  info "Starting QEMU local emulator"
+  info "Arch: $ARCH | Accel: $ACCEL"
+  info "Ports: Dashboard=$EMULATOR_DASHBOARD_PORT Backend=$EMULATOR_BACKEND_PORT MinIO=$EMULATOR_MINIO_PORT Inbucket=$EMULATOR_INBUCKET_PORT"
+
+  start_vm
+
+  info "VM: ${VM_RAM}MB / ${VM_CPUS} CPUs"
+
+  if ! wait_for_condition "deps services" "$READY_TIMEOUT" deps_ready; then
+    tail_vm_logs
+    exit 1
+  fi
+
+  if ! wait_for_condition "dashboard/backend" "$READY_TIMEOUT" app_ready; then
+    tail_vm_logs
+    exit 1
+  fi
+
+  log "All services are green."
+  info "Dashboard: http://localhost:${EMULATOR_DASHBOARD_PORT}"
+  info "Backend:   http://localhost:${EMULATOR_BACKEND_PORT}"
+}
+
+cmd_stop() {
+  stop_vm
+  log "QEMU emulator stopped."
+}
+
+cmd_reset() {
+  cmd_stop 2>/dev/null || true
+  rm -rf "$RUN_DIR"
+  log "Emulator state reset. Next start will be a fresh boot."
+}
+
+STATUS_FAILED=0
+
+print_service_status() {
+  local name="$1"
+  local port="$2"
+  local proto="$3"
+  local path="${4:-/}"
+  local expected_codes="${5:-200}"
+  if service_is_up "$port" "$proto" "$path" "$expected_codes"; then
+    echo -e "  ${GREEN}●${NC} $name (:$port)"
+  else
+    echo -e "  ${RED}●${NC} $name (:$port)"
+    STATUS_FAILED=1
+  fi
+}
+
+cmd_status() {
+  STATUS_FAILED=0
+  echo "VM:"
+  if is_running; then
+    echo -e "  ${GREEN}●${NC} emulator"
+  else
+    echo -e "  ${RED}●${NC} emulator"
+    STATUS_FAILED=1
+  fi
+  echo ""
+  echo "Services:"
+  print_service_status "Dashboard" "$EMULATOR_DASHBOARD_PORT" http /handler/sign-in
+  print_service_status "Backend" "$EMULATOR_BACKEND_PORT" http "/health?db=1"
+  print_service_status "MinIO" "$EMULATOR_MINIO_PORT" http /minio/health/live
+  print_service_status "Inbucket HTTP" "$EMULATOR_INBUCKET_PORT" http /
+  exit "$STATUS_FAILED"
+}
+
+cmd_bench() {
+  local elapsed
+  cmd_stop >/dev/null 2>&1 || true
+  SECONDS=0
+  cmd_start
+  elapsed="$SECONDS"
+  printf "Startup time: %.1fs\n" "$elapsed"
+}
+
+ACTION="start"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    start|stop|reset|status|bench)
+      ACTION="$1"
+      shift
+      ;;
+    *)
+      echo "Usage: $0 [start|stop|reset|status|bench]"
+      exit 1
+      ;;
+  esac
+done
+
+case "$ACTION" in
+  start) cmd_start ;;
+  stop) cmd_stop ;;
+  reset) cmd_reset ;;
+  status) cmd_status ;;
+  bench) cmd_bench ;;
+esac

package/dist/index.js

@@ -7,6 +7,7 @@ import * as path from "path";
 import { dirname, join, resolve } from "path";
 import { StackClientApp } from "@stackframe/js";
 import * as os from "os";
+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";
@@ -723,6 +724,60 @@ function registerProjectCommand(program) {
 
 //#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 parsed = Number(raw);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new CliError(`Invalid EMULATOR_BACKEND_PORT: ${raw}`);
+	return parsed;
+}
+function emulatorHome() {
+	return process.env.STACK_EMULATOR_HOME ?? join(homedir(), ".stack", "emulator");
+}
+function emulatorRunDir() {
+	return join(emulatorHome(), "run");
+}
+function emulatorImageDir() {
+	return join(emulatorHome(), "images");
+}
+function internalPckPath() {
+	return join(emulatorRunDir(), "vm", "internal-pck");
+}
+async function readInternalPck(timeoutMs = 6e4) {
+	const path = internalPckPath();
+	const deadline = Date.now() + timeoutMs;
+	let delay = 250;
+	while (Date.now() < deadline) {
+		if (existsSync(path)) {
+			const contents = readFileSync(path, "utf-8").trim();
+			if (contents) return contents;
+		}
+		await new Promise((r) => setTimeout(r, delay));
+		delay = Math.min(delay * 2, 2e3);
+	}
+	throw new CliError(`Timed out waiting for emulator internal publishable client key at ${path}`);
+}
+async function fetchEmulatorCredentials(pck, backendPort, configFile) {
+	const url = `http://127.0.0.1:${backendPort}/api/v1/internal/local-emulator/project`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"X-Stack-Project-Id": "internal",
+			"X-Stack-Access-Type": "client",
+			"X-Stack-Publishable-Client-Key": pck
+		},
+		body: JSON.stringify({ absolute_file_path: configFile })
+	});
+	if (!res.ok) throw new CliError(`Failed to initialize local emulator project (${res.status}): ${await res.text()}`);
+	const data = await res.json();
+	return {
+		project_id: data.project_id,
+		publishable_client_key: data.publishable_client_key,
+		secret_server_key: data.secret_server_key
+	};
+}
 function gh(args) {
 	try {
 		return execFileSync("gh", args, {
@@ -738,28 +793,57 @@ function gh(args) {
 		throw new CliError("GitHub CLI (gh) is required. Install: https://cli.github.com/");
 	}
 }
-function findQemuDir() {
-	for (const rel of ["docker/local-emulator/qemu", "../docker/local-emulator/qemu"]) {
-		const dir = resolve(process.cwd(), rel);
-		if (existsSync(join(dir, "run-emulator.sh"))) return dir;
-	}
-	throw new CliError("Could not find QEMU emulator directory. Run this from the stack-auth repo root.");
+function emulatorScriptsDir() {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const bundled = join(here, "emulator");
+	if (existsSync(join(bundled, "run-emulator.sh"))) return bundled;
+	const repo = resolve(here, "../../../docker/local-emulator/qemu");
+	if (existsSync(join(repo, "run-emulator.sh"))) return repo;
+	throw new CliError("Emulator scripts not found in CLI bundle.");
+}
+function emulatorSpawnEnv(extra) {
+	return {
+		...process.env,
+		EMULATOR_RUN_DIR: emulatorRunDir(),
+		EMULATOR_IMAGE_DIR: emulatorImageDir(),
+		...extra
+	};
 }
 function runEmulator(action, env) {
-	const qemuDir = findQemuDir();
-	return new Promise((resolve, reject) => {
-		const child = spawn(join(qemuDir, "run-emulator.sh"), [action], {
+	const scriptsDir = emulatorScriptsDir();
+	mkdirSync(emulatorRunDir(), { recursive: true });
+	mkdirSync(emulatorImageDir(), { recursive: true });
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn(join(scriptsDir, "run-emulator.sh"), [action], {
 			stdio: "inherit",
-			env: {
-				...process.env,
-				...env
-			},
-			cwd: qemuDir
+			env: emulatorSpawnEnv(env),
+			cwd: scriptsDir
 		});
-		child.on("close", (code) => code === 0 ? resolve() : reject(new CliError(`run-emulator.sh ${action} exited with code ${code}`)));
+		child.on("close", (code) => code === 0 ? resolvePromise() : reject(new CliError(`run-emulator.sh ${action} exited with code ${code}`)));
 		child.on("error", (err) => reject(new CliError(`Failed to run run-emulator.sh: ${err.message}`)));
 	});
 }
+function isEmulatorRunning() {
+	const scriptsDir = emulatorScriptsDir();
+	try {
+		execFileSync(join(scriptsDir, "run-emulator.sh"), ["status"], {
+			stdio: "pipe",
+			cwd: scriptsDir,
+			env: emulatorSpawnEnv()
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+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 runEmulator("start", { EMULATOR_ARCH: arch });
+}
 function resolveArch(raw) {
 	const arch = raw ?? (process.arch === "arm64" ? "arm64" : process.arch === "x64" ? "amd64" : null);
 	if (arch === "arm64" || arch === "amd64") return arch;
@@ -770,7 +854,7 @@ function pullRelease(arch, opts = {}) {
 	const branch = opts.branch ?? "dev";
 	const tag = opts.tag ?? `emulator-${branch}-latest`;
 	const asset = `stack-emulator-${arch}.qcow2`;
-	const imageDir = join(findQemuDir(), "images");
+	const imageDir = emulatorImageDir();
 	mkdirSync(imageDir, { recursive: true });
 	const dest = join(imageDir, asset);
 	const tmpDest = `${dest}.download`;
@@ -832,7 +916,7 @@ function registerEmulatorCommand(program) {
 				if (runs.length === 0) throw new CliError(`No successful build found for PR #${opts.pr} (branch: ${headRefName}).`);
 				runId = String(runs[0].databaseId);
 			}
-			const imageDir = join(findQemuDir(), "images");
+			const imageDir = emulatorImageDir();
 			mkdirSync(imageDir, { recursive: true });
 			const dest = join(imageDir, `stack-emulator-${arch}.qcow2`);
 			if (existsSync(dest)) unlinkSync(dest);
@@ -860,13 +944,64 @@ function registerEmulatorCommand(program) {
 			tag: opts.tag
 		});
 	});
-	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.").action(async (opts) => {
+	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);
-		if (!existsSync(join(findQemuDir(), "images", `stack-emulator-${arch}.qcow2`))) {
-			console.log("No emulator image found. Pulling latest...");
-			pullRelease(arch);
+		let resolvedConfigFile;
+		if (opts.configFile) {
+			resolvedConfigFile = resolve(opts.configFile);
+			if (!existsSync(resolvedConfigFile)) throw new CliError(`Config file not found: ${resolvedConfigFile}`);
+		}
+		if (isEmulatorRunning()) console.warn("Emulator already running, reusing existing instance.");
+		else await startEmulator(arch);
+		if (resolvedConfigFile) {
+			const creds = await fetchEmulatorCredentials(await readInternalPck(), emulatorBackendPort(), resolvedConfigFile);
+			console.log(JSON.stringify(creds, null, 2));
 		}
-		await runEmulator("start", { EMULATOR_ARCH: arch });
+	});
+	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);
+		let resolvedConfigFile;
+		if (opts.configFile) {
+			resolvedConfigFile = resolve(opts.configFile);
+			if (!existsSync(resolvedConfigFile)) throw new CliError(`Config file not found: ${resolvedConfigFile}`);
+		}
+		const alreadyRunning = isEmulatorRunning();
+		if (alreadyRunning) console.log("Emulator already running, reusing existing instance.");
+		else await startEmulator(arch);
+		const childEnv = { ...process.env };
+		if (resolvedConfigFile) {
+			const pck = await readInternalPck();
+			const backendPort = emulatorBackendPort();
+			const creds = await fetchEmulatorCredentials(pck, backendPort, resolvedConfigFile);
+			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.STACK_PUBLISHABLE_CLIENT_KEY = creds.publishable_client_key;
+			childEnv.NEXT_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;
+		}
+		const child = spawn(cmd, {
+			shell: true,
+			stdio: "inherit",
+			env: childEnv
+		});
+		const forward = (signal) => () => child.kill(signal);
+		const onSigint = forward("SIGINT");
+		const onSigterm = forward("SIGTERM");
+		process.on("SIGINT", onSigint);
+		process.on("SIGTERM", onSigterm);
+		child.on("close", (code) => {
+			process.off("SIGINT", onSigint);
+			process.off("SIGTERM", onSigterm);
+			const exitCode = code ?? 1;
+			if (alreadyRunning) process.exit(exitCode);
+			else {
+				console.log("\nStopping emulator...");
+				runEmulator("stop").catch(() => {}).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"));