@zitadel/cli 0.1.0-alpha.4 → 0.1.0-alpha.8

package/README.md

@@ -1,6 +1,6 @@
 # @zitadel/cli
 
-Scaffolds Zitadel auth (login, register, profile, middleware) into a Next.js app.
+Scaffolds Zitadel auth (login, register, profile, middleware) into a Next.js, React, Vue, Angular, or Nuxt app.
 
 ```sh
 npx @zitadel/cli@alpha start
@@ -15,8 +15,8 @@ automation when reproducibility matters.
 
 ## Requirements
 
-- Node 20+
-- Docker for the managed local Zitadel runtime
+- Node 24+
+- Docker only when using the optional Docker runtime backend
 - A Next.js project, or an empty directory where setup can scaffold one
 
 ## Quickstart
@@ -30,20 +30,21 @@ npx @zitadel/cli@alpha setup --server local
 npm run dev
 ```
 
-`start` runs a Docker-backed local Zitadel server and stores runtime data
-under `.zitadel/local/`. Alpha CLI versions use the matching
-`ghcr.io/zitadel/nextgen:<cli-version>` image by default; local/dev builds fall
-back to `ghcr.io/zitadel/nextgen:latest`. Override with `--image` or
-`ZITADEL_LOCAL_IMAGE` for advanced debugging.
+`start` runs the `@zitadel/server` npm binary by default and stores runtime data
+under `.zitadel/local/`. Remote-server setup can use `--server <url>` without
+starting a local runtime. Use `--runtime docker`, `--image`, or
+`ZITADEL_LOCAL_IMAGE` for advanced Docker backend debugging.
 `setup --server local` creates a project on that local server, asks which
 framework to scaffold when the directory is fresh, writes the Next.js app into
-the current directory, scaffolds `app/login`, `app/register`, and `proxy.ts`
-for Next 16+ or `middleware.ts` for older Next versions, writes `.env.local`
-and `.zitadel/`, and installs dependencies with the detected package manager.
-Pass `--skip-install` to install them yourself. The project's default user
-schema and login flow are provisioned server-side at creation time, so the CLI
-does not scaffold or upload them. Open `http://localhost:3000/login` to see the
-login page.
+the current directory, scaffolds `app/login`, `app/register`, `app/profile`, and
+`proxy.ts` for Next 16+ or `middleware.ts` for older Next versions. Fresh
+scaffolds also replace the starter `app/page.tsx` with links to sign in, create
+an account, and profile. Setup writes `.env.local` and `.zitadel/`, and installs
+dependencies with the detected package manager. Pass `--skip-install` to install
+them yourself. The project's default user schema and login flow are provisioned
+server-side at creation time, so the CLI does not scaffold or upload them. Open
+the dev server URL printed by your framework, register a user, log out, log back
+in, and end on the signed-in profile page.
 
 For a reproducible tester report, use the exact alpha train from the GitHub
 Release:
@@ -61,12 +62,12 @@ passkey can sign in with either credential.
 
 ## Other commands
 
-- `zitadel doctor` — verify the local Docker runtime and generated project files
-- `zitadel status` — summarise the local Docker runtime and project
+- `zitadel doctor` — verify the local runtime and generated project files
+- `zitadel status` — summarise the local runtime and project
 - `zitadel plan` — validate config and preview sync changes without mutation
 - `zitadel apply` — validate and upload repo config to Zitadel
 - `zitadel eject` — remove what setup wrote (alias: `zitadel uninstall`)
-- `zitadel start|stop|logs|reset` — manage the local Docker runtime
+- `zitadel start|stop|logs|reset` — manage the local runtime
 
 ## Reference
 
@@ -74,24 +75,23 @@ passkey can sign in with either credential.
 <summary>Full command reference</summary>
 
 <!-- commands -->
-
-- [`zitadel apply`](#zitadel-apply)
-- [`zitadel autocomplete [SHELL]`](#zitadel-autocomplete-shell)
-- [`zitadel commands`](#zitadel-commands)
-- [`zitadel doctor`](#zitadel-doctor)
-- [`zitadel eject`](#zitadel-eject)
-- [`zitadel help [COMMAND]`](#zitadel-help-command)
-- [`zitadel logs`](#zitadel-logs)
-- [`zitadel plan`](#zitadel-plan)
-- [`zitadel reset`](#zitadel-reset)
-- [`zitadel search`](#zitadel-search)
-- [`zitadel setup`](#zitadel-setup)
-- [`zitadel start`](#zitadel-start)
-- [`zitadel status`](#zitadel-status)
-- [`zitadel stop`](#zitadel-stop)
-- [`zitadel uninstall`](#zitadel-uninstall)
-- [`zitadel version`](#zitadel-version)
-- [`zitadel which`](#zitadel-which)
+* [`zitadel apply`](#zitadel-apply)
+* [`zitadel autocomplete [SHELL]`](#zitadel-autocomplete-shell)
+* [`zitadel commands`](#zitadel-commands)
+* [`zitadel doctor`](#zitadel-doctor)
+* [`zitadel eject`](#zitadel-eject)
+* [`zitadel help [COMMAND]`](#zitadel-help-command)
+* [`zitadel logs`](#zitadel-logs)
+* [`zitadel plan`](#zitadel-plan)
+* [`zitadel reset`](#zitadel-reset)
+* [`zitadel search`](#zitadel-search)
+* [`zitadel setup`](#zitadel-setup)
+* [`zitadel start`](#zitadel-start)
+* [`zitadel status`](#zitadel-status)
+* [`zitadel stop`](#zitadel-stop)
+* [`zitadel uninstall`](#zitadel-uninstall)
+* [`zitadel version`](#zitadel-version)
+* [`zitadel which`](#zitadel-which)
 
 ## `zitadel apply`
 
@@ -99,19 +99,19 @@ Validate and upload repo config to the platform.
 
 ```
 USAGE
-  $ zitadel apply [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
-    [-e development|preview|production]
+  $ zitadel apply [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [-e
+    development|preview|production]
 
 FLAGS
-  -c, --cwd=<value>                 Project directory to operate on.
-  -e, --environment=<option>        Target environment (default: development).
-                                    <options: development|preview|production>
-  -f, --force                       Overwrite protected files on conflict.
-  -n, --non-interactive             Disable prompts. Required when scripting or running as an agent.
-  -s, --server=<value>              Override the resolved server URL.
-      --debug                       Debug logging.
-      --dry-run                     Preview without mutating files or the platform.
-      --verbose                     Verbose logging.
+  -c, --cwd=<value>           Project directory to operate on.
+  -e, --environment=<option>  Target environment (default: development).
+                              <options: development|preview|production>
+  -f, --force                 Overwrite protected files on conflict.
+  -n, --non-interactive       Disable prompts. Required when scripting or running as an agent.
+  -s, --server=<value>        Override the resolved server URL.
+      --debug                 Debug logging.
+      --dry-run               Preview without mutating files or the platform.
+      --verbose               Verbose logging.
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -187,7 +187,7 @@ Verify local runtime and project state.
 ```
 USAGE
   $ zitadel doctor [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [--fix]
-    [--image <value>] [--port <value>]
+    [--image <value>] [--port <value>] [--runtime binary|docker]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -199,6 +199,8 @@ FLAGS
       --fix              Re-apply missing managed files.
       --image=<value>    Container image to check.
       --port=<value>     [default: 8080] Local HTTP port.
+      --runtime=<option> Local runtime backend.
+                         <options: binary|docker>
       --verbose          Verbose logging.
 
 GLOBAL FLAGS
@@ -288,19 +290,19 @@ Validate config without mutation and preview the sync diff.
 
 ```
 USAGE
-  $ zitadel plan [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
-    [-e development|preview|production]
+  $ zitadel plan [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [-e
+    development|preview|production]
 
 FLAGS
-  -c, --cwd=<value>                 Project directory to operate on.
-  -e, --environment=<option>        Target environment (default: development).
-                                    <options: development|preview|production>
-  -f, --force                       Overwrite protected files on conflict.
-  -n, --non-interactive             Disable prompts. Required when scripting or running as an agent.
-  -s, --server=<value>              Override the resolved server URL.
-      --debug                       Debug logging.
-      --dry-run                     Preview without mutating files or the platform.
-      --verbose                     Verbose logging.
+  -c, --cwd=<value>           Project directory to operate on.
+  -e, --environment=<option>  Target environment (default: development).
+                              <options: development|preview|production>
+  -f, --force                 Overwrite protected files on conflict.
+  -n, --non-interactive       Disable prompts. Required when scripting or running as an agent.
+  -s, --server=<value>        Override the resolved server URL.
+      --debug                 Debug logging.
+      --dry-run               Preview without mutating files or the platform.
+      --verbose               Verbose logging.
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -356,7 +358,7 @@ Create a Zitadel project and scaffold local auth.
 ```
 USAGE
   $ zitadel setup [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
-    [--framework next] [--renderer react|web-component] [--skip-install]
+    [--framework next|nuxt|react|vue|angular] [--renderer react|web-component] [--dev-port <value>] [--skip-install]
 
 FLAGS
   -c, --cwd=<value>         Project directory to operate on.
@@ -364,9 +366,11 @@ FLAGS
   -n, --non-interactive     Disable prompts. Required when scripting or running as an agent.
   -s, --server=<value>      Override the resolved server URL.
       --debug               Debug logging.
+      --dev-port=<value>    Dev-server port; also the issuer origin registered with Zitadel. Defaults to the detected
+                            port. Use distinct ports to run several scaffolded apps side by side.
       --dry-run             Preview without mutating files or the platform.
       --framework=<option>  Framework to target.
-                            <options: next>
+                            <options: next|nuxt|react|vue|angular>
       --renderer=<option>   Renderer (default: react).
                             <options: react|web-component>
       --skip-install        Do not install dependencies after setup updates package.json.
@@ -380,6 +384,8 @@ DESCRIPTION
 
 EXAMPLES
   $ zitadel setup --framework next
+
+  $ zitadel setup --framework react --dev-port 3000
 ```
 
 ## `zitadel start`
@@ -389,7 +395,7 @@ Start a local Zitadel server.
 ```
 USAGE
   $ zitadel start [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [--image
-    <value>] [--port <value>]
+    <value>] [--port <value>] [--runtime binary|docker]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -400,6 +406,8 @@ FLAGS
       --dry-run          Preview without mutating files or the platform.
       --image=<value>    Container image to run.
       --port=<value>     [default: 8080] Local HTTP port.
+      --runtime=<option> Local runtime backend.
+                         <options: binary|docker>
       --verbose          Verbose logging.
 
 GLOBAL FLAGS
@@ -537,7 +545,6 @@ EXAMPLES
 ```
 
 _See code: [@oclif/plugin-which](https://github.com/oclif/plugin-which/blob/3.2.55/src/commands/which.ts)_
-
 <!-- commandsstop -->
 
 </details>

package/SKILLS.md

@@ -4,8 +4,8 @@ description: >-
   Set up and manage Zitadel authentication in a local project with the
   agent-friendly `zitadel` CLI. Use when the user wants to add login,
   registration, or session handling, create a Zitadel project, scaffold auth
-  routes for a Next.js App Router app, or plan and apply Zitadel config changes
-  from repo state.
+  for a Next.js, React, Vue, Angular, or Nuxt app, or plan and apply Zitadel
+  config changes from repo state.
 ---
 
 # Zitadel CLI
@@ -42,7 +42,7 @@ Each invocation prints one JSON object:
 - On failure: `code` (e.g. `E_VALIDATION`, `E_NETWORK`, `E_CONFLICT`) and
   `message`.
 - `next_commands`: the suggested follow-ups. Prefer these over free-text hints.
-- `E_LOCAL_SERVER_NOT_RUNNING`: start the local Docker runtime with
+- `E_LOCAL_SERVER_NOT_RUNNING`: start the local runtime with
   `npx @zitadel/cli@alpha start`, then retry with `--server local`.
 
 Exit codes mirror the error class (3 = validation, 4 = network, 5 = conflict,
@@ -56,29 +56,33 @@ layer, not the envelope.
   and login flow are provisioned server-side at creation, so setup neither
   scaffolds nor uploads them. Agents must pass `--framework` when scaffolding
   into a fresh directory; interactive humans can omit it and choose from the
-  prompt. Flags: `--framework`, `--renderer`.
+  prompt. Flags: `--framework next|react|vue|angular|nuxt`, `--renderer
+  react|web-component` (selects the Next.js auth-page renderer; accepted for any
+  framework and recorded in `zitadel.json` branding, but only Next varies its
+  generated templates by it), `--dev-port` (dev-server port, also the issuer
+  origin registered with Zitadel — use distinct ports to run several scaffolded
+  apps side by side), `--skip-install`.
 - `plan` — validate config and preview the sync diff without mutating anything.
 - `apply` — validate and upload repo config to the platform.
 - `doctor` — verify generated app files and local state once `zitadel.json`
-  exists. Local Docker runtime prerequisites are advisory warnings unless an
-  existing managed runtime is unhealthy; `--fix` re-applies missing managed
-  files.
-- `status` — summarize the local Docker runtime and project state.
+  exists. The default local runtime is the `@zitadel/server` npm binary;
+  Docker checks apply only when using `--runtime docker` or `--image`.
+  `--fix` re-applies missing managed files.
+- `status` — summarize the local runtime and project state.
 - `eject` (alias `uninstall`) — remove managed files and local Zitadel state;
   requires `--force` when non-interactive.
-- `start` — start the managed local Zitadel container and persist runtime
-  metadata under `.zitadel/local/runtime.json`.
-- `stop` — stop/remove the managed container while preserving
+- `start` — start the managed local Zitadel server and persist runtime metadata
+  under `.zitadel/local/runtime.json`. Use `--runtime docker` or `--image` for
+  the Docker backend.
+- `stop` — stop the managed runtime while preserving
   `.zitadel/local/nextgen-data`.
-- `logs` — print managed container logs; `--follow` streams in human mode.
-- `reset` — stop/remove the managed container and delete local runtime data;
+- `logs` — print managed runtime logs; `--follow` streams in human mode.
+- `reset` — stop/remove the managed runtime and delete local runtime data;
   requires `--force` when non-interactive.
 
-Alpha releases are lockstep trains. `npx @zitadel/cli@alpha start` runs the
-latest tested alpha server image, and
-`npx @zitadel/cli@0.1.0-alpha.N start` runs
-`ghcr.io/zitadel/nextgen:0.1.0-alpha.N`. `zitadel start --image <ref>` remains
-the explicit image override for debugging.
+Alpha releases are fixed product package trains. `npx @zitadel/cli@alpha start`
+uses the matching `@zitadel/server` package by default. `zitadel start --runtime
+docker --image <ref>` remains the explicit image override for debugging.
 
 ## Golden path
 
@@ -99,6 +103,44 @@ npx @zitadel/cli@0.1.0-alpha.N start --non-interactive --json
 npx @zitadel/cli@0.1.0-alpha.N setup --framework next --server local --non-interactive --json
 ```
 
+After `setup`, follow `data.next_commands` to start the app. Prove the generated
+auth flow in a visible browser by registering a unique user, logging out, logging
+back in with the same email/password, and ending on the signed-in profile page.
+Do not treat a rendered login or registration form as completion.
+
+### Driving the login UI
+
+`<zitadel-login>` and `<zitadel-logout>` are Lit elements with open shadow
+roots. The stable automation hooks live inside nested shadow roots, so a flat
+`document.querySelector('[data-testid="zitadel-field-email-input"]')` will not
+find them. Browser drivers with shadow-DOM-aware locators, such as Playwright,
+can target the hooks directly. Generic DOM-eval drivers should pierce shadow
+roots recursively:
+
+```js
+function deepQuery(sel, root = document) {
+  const hit = root.querySelector(sel);
+  if (hit) return hit;
+  for (const el of root.querySelectorAll("*")) {
+    if (el.shadowRoot) {
+      const result = deepQuery(sel, el.shadowRoot);
+      if (result) return result;
+    }
+  }
+  return null;
+}
+```
+
+Use `zitadel-field-email-input`, `zitadel-field-password-input`, and
+`zitadel-action-submit-button` for sign-in and registration. For sign-out, open
+the user menu button if needed, then pierce to `.signout-btn`; Playwright-style
+locators may use `zitadel-logout .signout-btn`. The canonical component hook
+list lives in `packages/components/README.md`.
+
+The checked-in automated regression path is `moon run workspace:journey`, which
+exercises fresh-app setup plus registration, logout, and login across the
+supported frameworks.
+
 Repo config is authoritative: edit `zitadel.json` or files under `.zitadel/`,
 then re-run `plan` and `apply`. Managed files carry a marker comment; `eject`
 removes only files that still carry it, preserving anything the user replaced.

package/dist/commands/apply.mjs

@@ -1,6 +1,6 @@
-import { t as BaseCommand } from "../oclif-B3Qhw0cj.mjs";
-import { o as readZitadelSecret } from "../project-kWWyS7fS.mjs";
-import { a as makeSyncers, i as runSyncLoop, n as summarizePlan, o as environmentSchema, r as buildSyncPlan, t as renderPlan } from "../sync-CHXZqYR7.mjs";
+import { t as BaseCommand } from "../oclif-VkCTGIEk.mjs";
+import { o as readZitadelSecret } from "../project-CKAHtHML.mjs";
+import { a as makeSyncers, i as runSyncLoop, n as summarizePlan, o as environmentSchema, r as buildSyncPlan, t as renderPlan } from "../sync-B5lqgQO3.mjs";
 import { Flags } from "@oclif/core";
 import { createZitadelClient } from "@zitadel/api/client";
 import { consola as consola$1 } from "consola";

package/dist/commands/doctor.mjs

@@ -1,7 +1,8 @@
-import { C as isObject, E as ZitadelError, a as DEFAULT_LOCAL_SERVER_PORT, b as publicCliCommand, c as checkLocalServerHealth, f as isPortAvailable, h as readRuntimeMetadata, l as defaultLocalServerImageForCliVersion, m as localServerUrl, s as assertLocalStateWritable, t as BaseCommand } from "../oclif-B3Qhw0cj.mjs";
-import { r as issuerFromPort, t as createOrca } from "../orca-BGM8VCgQ.mjs";
-import { a as readZitadelConfig, i as readRendererId, o as readZitadelSecret, r as readDevelopmentIssuer, t as hasZitadelConfig } from "../project-kWWyS7fS.mjs";
-import { o as imageAvailable, r as dockerAvailable } from "../docker-B4zvLujy.mjs";
+import { D as ZitadelError, a as DEFAULT_LOCAL_SERVER_PORT, c as checkLocalServerHealth, f as isPortAvailable, h as readRuntimeMetadata, l as defaultLocalServerImageForCliVersion, m as localServerUrl, s as assertLocalStateWritable, t as BaseCommand, w as isObject, x as publicCliCommand } from "../oclif-VkCTGIEk.mjs";
+import { r as issuerFromPort, t as createOrca } from "../orca-CfKDQRop.mjs";
+import { a as readZitadelConfig, i as readRendererId, o as readZitadelSecret, r as readDevelopmentIssuer, t as hasZitadelConfig } from "../project-CKAHtHML.mjs";
+import { d as assertServerPackageAvailable, o as imageAvailable, r as dockerAvailable } from "../docker-BA78SdC2.mjs";
+import { n as dockerUnavailableMessage, t as dockerRuntimeGuidance } from "../docker-guidance-BvfpmsDj.mjs";
 import { Flags } from "@oclif/core";
 import consola from "consola";
 import { join } from "node:path";
@@ -247,6 +248,7 @@ const SANITY_CHECKS = [
 //#endregion
 //#region src/commands/doctor/index.ts
 const LOCAL_RUNTIME_CHECK_NAMES = new Set([
+	"server-binary",
 	"docker-cli",
 	"image",
 	"state-dir",
@@ -274,6 +276,10 @@ var Doctor = class Doctor extends BaseCommand {
 		port: Flags.integer({
 			description: "Local HTTP port.",
 			default: DEFAULT_LOCAL_SERVER_PORT
+		}),
+		runtime: Flags.string({
+			description: "Local runtime backend.",
+			options: ["binary", "docker"]
 		})
 	};
 	async run() {
@@ -284,8 +290,15 @@ var Doctor = class Doctor extends BaseCommand {
 			source: localServerUrl(port)
 		});
 		const { cwd, dryRun } = this.meta;
+		const existingRuntime = await readRuntimeMetadata(cwd);
+		const runtimeBackend = resolveRuntimeBackend({
+			runtime: flags.runtime,
+			image: flags.image,
+			envImage: this.meta.env.ZITADEL_LOCAL_IMAGE,
+			existingRuntime
+		});
 		const image = flags.image ?? this.meta.env.ZITADEL_LOCAL_IMAGE ?? defaultLocalServerImageForCliVersion(this.meta.cliVersion);
-		const runtimeChecks = await runLocalRuntimeChecks(cwd, image, port);
+		const runtimeChecks = await runLocalRuntimeChecks(cwd, runtimeBackend, image, port);
 		const hasConfig = await hasZitadelConfig(cwd);
 		const ctx = {
 			cwd,
@@ -308,13 +321,19 @@ var Doctor = class Doctor extends BaseCommand {
 		const checks = [...runtimeChecks, ...projectChecks];
 		const failed = checks.filter((check) => check.status === "fail");
 		const warnings = checks.filter((check) => check.status === "warn");
+		const warningAdvice = advisoryForWarnings(warnings, this.meta.cliVersion);
 		const data = {
 			title: failed.length > 0 ? "Zitadel doctor found issues." : warnings.length > 0 ? "Zitadel doctor passed with warnings." : "Zitadel doctor passed.",
 			ok: failed.length === 0,
-			image,
+			runtime: runtimeBackend,
+			...runtimeBackend === "docker" ? { image } : {},
 			port,
 			project: { lifecycle: hasConfig ? "configured" : "not-configured" },
-			checks
+			checks,
+			...warningAdvice ? {
+				next_actions: warningAdvice.nextActions,
+				next_commands: warningAdvice.nextCommands
+			} : {}
 		};
 		if (failed.length > 0) {
 			const advice = failureAdvice(failed, image, port, this.meta.cliVersion);
@@ -333,10 +352,17 @@ var Doctor = class Doctor extends BaseCommand {
 };
 function failureAdvice(failed, image, port, cliVersion) {
 	const failedNames = new Set(failed.map((check) => check.name));
-	if (failedNames.has("docker-cli")) return {
-		hint: "Docker is required for `zitadel start`, but the Docker daemon is not reachable. Install or start Docker, then rerun `zitadel doctor`.",
-		nextCommands: ["docker version", publicCliCommand("doctor", cliVersion)]
+	if (failedNames.has("server-binary")) return {
+		hint: "The Zitadel server npm package is not available. Reinstall the CLI package, then retry.",
+		nextCommands: [publicCliCommand("doctor", cliVersion)]
 	};
+	if (failedNames.has("docker-cli")) {
+		const advice = dockerRuntimeGuidance("doctor", cliVersion);
+		return {
+			hint: advice.hint,
+			nextCommands: advice.nextCommands
+		};
+	}
 	if (failedNames.has("image")) return {
 		hint: "The local Zitadel image is not available. Check Docker registry access, build it locally, or pass --image / ZITADEL_LOCAL_IMAGE.",
 		nextCommands: [`docker pull ${image}`, publicCliCommand("doctor", cliVersion)]
@@ -365,8 +391,31 @@ function failureAdvice(failed, image, port, cliVersion) {
 		nextCommands: [publicCliCommand("doctor", cliVersion)]
 	};
 }
-async function runLocalRuntimeChecks(cwd, image, port) {
+function advisoryForWarnings(warnings, cliVersion) {
+	if (!warnings.some((check) => check.name === "docker-cli")) return;
+	const advice = dockerRuntimeGuidance("doctor", cliVersion);
+	return {
+		nextActions: advice.nextActions,
+		nextCommands: advice.nextCommands
+	};
+}
+async function runLocalRuntimeChecks(cwd, runtimeBackend, image, port) {
 	const runtime = await readRuntimeMetadata(cwd);
+	if (runtimeBackend === "binary") return [
+		await check("server-binary", "Server npm package is available", async () => {
+			return `@zitadel/server ${await assertServerPackageAvailable()} is available`;
+		}),
+		await check("state-dir", "Local state directory is writable", async () => {
+			const probe = await assertLocalStateWritable(cwd);
+			return probe.checkedPath === probe.targetPath ? `${probe.targetPath} is writable` : `${probe.targetPath} can be created (${probe.checkedPath} is writable)`;
+		}, "warn"),
+		await check("port", `Port ${String(port)} is available`, async () => {
+			if (runtime && await checkLocalServerHealth(runtime.server_url)) return `${runtime.server_url} is already healthy`;
+			if (!await isPortAvailable(port)) throw new Error(`Port ${String(port)} is already in use`);
+			return `Port ${String(port)} is available`;
+		}, "warn"),
+		await checkRuntime(runtime, runtimeBackend)
+	];
 	const docker = await check("docker-cli", "Docker is reachable", async () => {
 		let result;
 		try {
@@ -399,13 +448,23 @@ async function runLocalRuntimeChecks(cwd, image, port) {
 			if (!await isPortAvailable(port)) throw new Error(`Port ${String(port)} is already in use`);
 			return `Port ${String(port)} is available`;
 		}, "warn"),
-		await check("runtime", "Existing local runtime is healthy", async () => {
-			if (!runtime) return "No existing runtime metadata";
-			if (!await checkLocalServerHealth(runtime.server_url)) throw new Error(`${runtime.server_url} did not respond to /healthz`);
-			return `${runtime.server_url} is healthy`;
-		})
+		await checkRuntime(runtime, runtimeBackend)
 	];
 }
+async function checkRuntime(runtime, runtimeBackend) {
+	return check("runtime", "Existing local runtime is healthy", async () => {
+		if (!runtime) return "No existing runtime metadata";
+		if (runtime.backend !== runtimeBackend) throw new Error(`Existing local runtime uses ${runtime.backend}; run start --runtime ${runtimeBackend} to switch backends.`);
+		if (!await checkLocalServerHealth(runtime.server_url)) throw new Error(`${runtime.server_url} did not respond to /healthz`);
+		return `${runtime.server_url} is healthy`;
+	});
+}
+function resolveRuntimeBackend(input) {
+	if (input.runtime === "binary" || input.runtime === "docker") return input.runtime;
+	if (input.existingRuntime) return input.existingRuntime.backend;
+	if (input.image || input.envImage) return "docker";
+	return "binary";
+}
 async function check(name, fallback, run, failureStatus = "fail") {
 	try {
 		return {
@@ -421,10 +480,6 @@ async function check(name, fallback, run, failureStatus = "fail") {
 		};
 	}
 }
-function dockerUnavailableMessage(error) {
-	const detail = error instanceof Error ? error.message : String(error);
-	return `Docker is not reachable${detail.trim() ? ` (${detail.trim()})` : ""}; \`zitadel start\` needs Docker, but cloud setup can continue.`;
-}
 function imageUnavailableMessage(image, error) {
 	const detail = error instanceof Error ? error.message : String(error);
 	return `Image ${image} is not available to Docker${detail.trim() ? ` (${detail.trim()})` : ""}; \`zitadel start\` may need a pull or a different image.`;