@zitadel/cli 0.1.0-alpha.5 → 0.1.0-alpha.9

package/README.md

@@ -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,11 +30,10 @@ 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`, `app/profile`, and
@@ -63,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
 
@@ -188,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.
@@ -200,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
@@ -394,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.
@@ -405,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

package/SKILLS.md

@@ -42,8 +42,11 @@ 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`.
+- `E_PORT_IN_USE`: the requested local runtime port already has a listener.
+  Stop that process, run `npx @zitadel/cli@alpha stop --all` for host-wide
+  CLI-managed local runtimes, or choose another `start --port`.
 
 Exit codes mirror the error class (3 = validation, 4 = network, 5 = conflict,
 1 = auth, 2 = not-implemented). An unknown command is handled by the CLI's help
@@ -65,25 +68,26 @@ layer, not the envelope.
 - `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
-  `.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;
+- `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`. Use `stop --all` to sweep all discovered
+  host-wide CLI-managed local runtime processes, including healthy runtimes
+  from other local projects; it does not kill arbitrary `/healthz` listeners.
+- `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
 
@@ -107,10 +111,40 @@ npx @zitadel/cli@0.1.0-alpha.N setup --framework next --server local --non-inter
 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. If browser DOM
-snapshots are sparse, target the component hooks exposed by the generated UI:
-`zitadel-field-email-input`, `zitadel-field-password-input`, and
-`zitadel-action-submit-button`.
+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`

package/dist/commands/apply.mjs

@@ -1,6 +1,6 @@
-import { t as BaseCommand } from "../oclif-2t97lHfY.mjs";
-import { o as readZitadelSecret } from "../project-IzPVR0Pr.mjs";
-import { a as makeSyncers, i as runSyncLoop, n as summarizePlan, o as environmentSchema, r as buildSyncPlan, t as renderPlan } from "../sync-Df9S8Pio.mjs";
+import { t as BaseCommand } from "../oclif-B7lBzh3R.mjs";
+import { o as readZitadelSecret } from "../project-Cd0L3PtM.mjs";
+import { a as makeSyncers, i as runSyncLoop, n as summarizePlan, o as environmentSchema, r as buildSyncPlan, t as renderPlan } from "../sync-BojoQm2P.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,10 @@
-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-2t97lHfY.mjs";
-import { r as issuerFromPort, t as createOrca } from "../orca-CYqJP4ZJ.mjs";
-import { a as readZitadelConfig, i as readRendererId, o as readZitadelSecret, r as readDevelopmentIssuer, t as hasZitadelConfig } from "../project-IzPVR0Pr.mjs";
-import { o as imageAvailable, r as dockerAvailable } from "../docker--EAWr_WY.mjs";
+import { C as isObject, E as ZitadelError, a as DEFAULT_LOCAL_SERVER_PORT, b as publicCliCommand, c as checkLocalServerHealth, l as defaultLocalServerImageForCliVersion, m as readRuntimeMetadata, p as localServerUrl, s as assertLocalStateWritable, t as BaseCommand } from "../oclif-B7lBzh3R.mjs";
+import { i as issuerFromPort, t as createOrca } from "../orca-U142Wrau.mjs";
+import { a as readZitadelConfig, i as readRendererId, o as readZitadelSecret, r as readDevelopmentIssuer, t as hasZitadelConfig } from "../project-Cd0L3PtM.mjs";
+import { n as listenersForPort } from "../ports-B09RjuHx.mjs";
+import { d as assertServerPackageAvailable, o as imageAvailable, r as dockerAvailable } from "../docker-CnGQK3ZK.mjs";
+import { n as dockerUnavailableMessage, t as dockerRuntimeGuidance } from "../docker-guidance-ypN3IM3o.mjs";
+import { t as discoverManagedRuntimeProcesses } from "../processes-Cw8TO1SY.mjs";
 import { Flags } from "@oclif/core";
 import consola from "consola";
 import { join } from "node:path";
@@ -247,6 +250,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 +278,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 +292,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,17 +323,23 @@ 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);
-			throw new ZitadelError("E_VALIDATION", "Zitadel doctor found issues", {
+			throw new ZitadelError(failed.some((check) => check.name === "port") ? "E_PORT_IN_USE" : "E_VALIDATION", "Zitadel doctor found issues", {
 				hint: advice.hint,
 				nextCommands: advice.nextCommands,
 				details: data
@@ -333,10 +354,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 +393,39 @@ function failureAdvice(failed, image, port, cliVersion) {
 		nextCommands: [publicCliCommand("doctor", cliVersion)]
 	};
 }
-async function runLocalRuntimeChecks(cwd, image, port) {
+function advisoryForWarnings(warnings, cliVersion) {
+	const nextActions = [];
+	const nextCommands = [];
+	if (warnings.some((check) => check.name === "docker-cli")) {
+		const advice = dockerRuntimeGuidance("doctor", cliVersion);
+		nextActions.push(...advice.nextActions);
+		nextCommands.push(...advice.nextCommands);
+	}
+	if (hasManagedRuntimeProcesses(warnings.find((check) => check.name === "managed-runtime-processes"))) {
+		nextActions.push("Review other host-wide CLI-managed local Zitadel runtimes before starting a new one.");
+		nextCommands.push(publicCliCommand("stop --all", cliVersion));
+	}
+	if (nextActions.length === 0 && nextCommands.length === 0) return;
+	return {
+		nextActions: unique(nextActions),
+		nextCommands: unique(nextCommands)
+	};
+}
+async function runLocalRuntimeChecks(cwd, runtimeBackend, image, port) {
 	const runtime = await readRuntimeMetadata(cwd);
+	const managedRuntimeCheck = await checkManagedRuntimeProcesses(runtime);
+	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`, () => checkPortAvailability(runtime, port)),
+		await checkRuntime(runtime, runtimeBackend),
+		managedRuntimeCheck
+	];
 	const docker = await check("docker-cli", "Docker is reachable", async () => {
 		let result;
 		try {
@@ -394,18 +453,87 @@ async function runLocalRuntimeChecks(cwd, image, port) {
 			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 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 check("port", `Port ${String(port)} is available`, () => checkPortAvailability(runtime, port)),
+		await checkRuntime(runtime, runtimeBackend),
+		managedRuntimeCheck
 	];
 }
+async function checkPortAvailability(runtime, port) {
+	if (runtime?.port === port && await checkLocalServerHealth(runtime.server_url)) return `${runtime.server_url} is already healthy`;
+	const listeners = await listenersForPort(port);
+	if (listeners.length > 0) throw new PortInUseCheckError(port, localServerUrl(port), listeners);
+	return `Port ${String(port)} is available`;
+}
+var PortInUseCheckError = class extends Error {
+	constructor(port, serverUrl, listeners) {
+		super(`Port ${String(port)} is already in use by ${formatListeners(listeners)}`);
+		this.port = port;
+		this.serverUrl = serverUrl;
+		this.listeners = listeners;
+	}
+};
+async function checkManagedRuntimeProcesses(runtime) {
+	const discovery = await discoverManagedRuntimeProcesses();
+	if (!discovery.supported) return {
+		name: "managed-runtime-processes",
+		status: "warn",
+		message: "Managed local runtime process discovery is unavailable.",
+		details: {
+			supported: false,
+			error: discovery.error
+		}
+	};
+	const processes = additionalManagedRuntimeProcesses(discovery.processes, runtime);
+	if (processes.length === 0) return {
+		name: "managed-runtime-processes",
+		status: "pass",
+		message: "No additional host-wide managed local runtime processes found.",
+		details: {
+			supported: true,
+			scope: "host",
+			processes: []
+		}
+	};
+	return {
+		name: "managed-runtime-processes",
+		status: "warn",
+		message: `${String(processes.length)} other host-wide managed local runtime process${processes.length === 1 ? "" : "es"} found.`,
+		details: {
+			supported: true,
+			scope: "host",
+			processes
+		}
+	};
+}
+function additionalManagedRuntimeProcesses(processes, runtime) {
+	if (runtime?.backend !== "binary") return processes;
+	return processes.filter((processInfo) => processInfo.pid !== runtime.pid && processInfo.ppid !== runtime.pid);
+}
+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 formatListeners(listeners) {
+	return listeners.map((listener) => [listener.command ?? "unknown", listener.pid ? `pid ${String(listener.pid)}` : void 0].filter(Boolean).join(" ")).join(", ");
+}
+function hasManagedRuntimeProcesses(check) {
+	if (!check || check.status !== "warn") return false;
+	const details = check.details;
+	return typeof details === "object" && details !== null && "supported" in details && details.supported === true && Array.isArray(details.processes) && (details.processes?.length ?? 0) > 0;
+}
+function unique(values) {
+	return [...new Set(values)];
+}
+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 {
@@ -414,6 +542,16 @@ async function check(name, fallback, run, failureStatus = "fail") {
 			message: await run()
 		};
 	} catch (error) {
+		if (error instanceof PortInUseCheckError) return {
+			name,
+			status: failureStatus,
+			message: error.message,
+			details: {
+				port: error.port,
+				server_url: error.serverUrl,
+				listeners: error.listeners
+			}
+		};
 		return {
 			name,
 			status: failureStatus,
@@ -421,10 +559,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.`;