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

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
@@ -37,13 +37,15 @@ back to `ghcr.io/zitadel/nextgen:latest`. Override with `--image` or
 `ZITADEL_LOCAL_IMAGE` for advanced 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:
@@ -74,24 +76,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 +100,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.
@@ -288,19 +289,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 +357,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 +365,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 +383,8 @@ DESCRIPTION
 
 EXAMPLES
   $ zitadel setup --framework next
+
+  $ zitadel setup --framework react --dev-port 3000
 ```
 
 ## `zitadel start`
@@ -537,7 +542,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
@@ -56,7 +56,12 @@ 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`
@@ -99,6 +104,14 @@ 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. 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`.
+
 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-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 { 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,7 @@
-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-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 { Flags } from "@oclif/core";
 import consola from "consola";
 import { join } from "node:path";

package/dist/commands/eject.mjs

@@ -1,6 +1,6 @@
-import { E as ZitadelError, t as BaseCommand } from "../oclif-B3Qhw0cj.mjs";
-import { t as createOrca } from "../orca-BGM8VCgQ.mjs";
-import { a as readZitadelConfig, i as readRendererId } from "../project-kWWyS7fS.mjs";
+import { D as ZitadelError, t as BaseCommand } from "../oclif-2t97lHfY.mjs";
+import { t as createOrca } from "../orca-CYqJP4ZJ.mjs";
+import { a as readZitadelConfig, i as readRendererId } from "../project-IzPVR0Pr.mjs";
 import { join } from "node:path";
 import { readFile, rename, rm, stat } from "node:fs/promises";
 //#region src/commands/eject.ts
@@ -16,7 +16,8 @@ async function resolveEjectActions(cwd) {
 		rootConfigFiles: ["zitadel.json"],
 		directories: [".zitadel"],
 		envBackups: [".env.local"],
-		dependencies: []
+		dependencies: [],
+		configEdits: []
 	};
 	const orca = createOrca();
 	const framework = await orca.tryDetect(cwd);
@@ -114,7 +115,12 @@ var Eject = class Eject extends BaseCommand {
 			});
 			removed.push(rel);
 		}
-		if (removed.length === 0 && backedUp.length === 0) return this.emit({
+		const manualSteps = actions.configEdits.map((rel) => {
+			if (rel === "package.json" || rel.endsWith("/package.json")) return `Remove the "dev" script setup added to ${rel}`;
+			if (rel === "angular.json" || rel.endsWith("/angular.json")) return `Remove the Zitadel proxyConfig (and dev-server port) from the serve target in ${rel}`;
+			return `Remove the Zitadel configuration block from ${rel}`;
+		});
+		if (removed.length === 0 && backedUp.length === 0 && manualSteps.length === 0) return this.emit({
 			status: "skipped",
 			reason: "nothing-to-eject",
 			data: { cwd }
@@ -127,7 +133,8 @@ var Eject = class Eject extends BaseCommand {
 				files_removed: removed,
 				files_preserved: preserved,
 				backed_up: backedUp,
-				next_commands: nextCommands
+				next_commands: nextCommands,
+				manual_steps: manualSteps
 			}
 		});
 	}

package/dist/commands/eject.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"eject.mjs","names":[],"sources":["../../src/commands/eject.ts"],"sourcesContent":["import { readFile, rename, rm, stat } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { BaseCommand, type JsonEnvelope } from \"../lib/oclif\";\nimport { ZitadelError } from \"../lib/errors\";\nimport { createOrca } from \"../lib/orca\";\nimport type { EjectActions } from \"../lib/orca/patchers/types\";\nimport { MANAGED_MARKER } from \"../lib/paths\";\nimport { readRendererId, readZitadelConfig } from \"../lib/project\";\n\n/**\n * Asks the framework patcher which artifacts it owns. Falls back to the\n * framework-agnostic set (`zitadel.json`, `.zitadel/`, `.env.local`) when the\n * framework or its patcher cannot be resolved, so an orphaned/partial project\n * can still be cleaned up.\n */\nasync function resolveEjectActions(cwd: string): Promise<EjectActions> {\n  const fallback: EjectActions = {\n    markedFiles: [],\n    rootConfigFiles: [\"zitadel.json\"],\n    directories: [\".zitadel\"],\n    envBackups: [\".env.local\"],\n    dependencies: [],\n  };\n  const orca = createOrca();\n  const framework = await orca.tryDetect(cwd);\n  if (!framework) {\n    return fallback;\n  }\n  try {\n    const config = await readZitadelConfig(cwd).catch(() => ({}) as Record<string, unknown>);\n    return orca.patcherFor(framework.id).artifacts({\n      framework,\n      rendererId: readRendererId(config),\n    });\n  } catch {\n    return fallback;\n  }\n}\n\n/**\n * Builds the `next_commands` envelope field — manual follow-ups `eject` can't\n * safely run itself: deleting the `.env.local.ejected-*` backups it created\n * (only when some were made), and uninstalling the SDK packages the patcher\n * added (the CLI never modifies the user's `package.json` + lockfile +\n * `node_modules` directly; it just suggests the command).\n */\nfunction assembleNextCommands(\n  backedUp: ReadonlyArray<unknown>,\n  dependencies: ReadonlyArray<string>,\n): ReadonlyArray<string> {\n  const commands: string[] = [];\n  if (backedUp.length > 0) {\n    commands.push(\"rm -f .env.local.ejected-*\");\n  }\n  for (const dep of dependencies) {\n    commands.push(`npm uninstall ${dep}`);\n  }\n  return commands;\n}\n\nasync function pathExists(path: string): Promise<boolean> {\n  try {\n    await stat(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * `zitadel eject` — remove managed files and local Zitadel state.\n *\n * Removes Zitadel-managed files from the project, leaving the remote project\n * untouched. The set of files comes from the framework patcher's\n * {@link import(\"../lib/orca/patchers/types\").Patcher.artifacts}, so the patcher\n * is the single source of truth for what its integration owns.\n *\n * Marked code files are removed only when they still carry the managed marker\n * (user-replaced files are preserved); `zitadel.json` is removed; `.env.local`\n * is renamed to a timestamped backup; and `.zitadel/` is removed wholesale.\n * `--dry-run` reports without touching the filesystem; non-interactive runs\n * require `--force`.\n */\nexport default class Eject extends BaseCommand {\n  static override description = \"Remove managed files and local Zitadel state.\";\n  static override aliases = [\"uninstall\"];\n\n  async run(): Promise<JsonEnvelope> {\n    const { flags } = await this.parse(Eject);\n    await this.toMeta(flags);\n    const { cwd, force, nonInteractive, dryRun } = this.meta;\n\n    if (!force && nonInteractive) {\n      throw new ZitadelError(\"E_VALIDATION\", \"Eject requires --force in non-interactive mode\", {\n        hint: \"Re-run with --force to confirm deletion of managed files.\",\n      });\n    }\n\n    const actions = await resolveEjectActions(cwd);\n    const removed: string[] = [];\n    const preserved: string[] = [];\n    const backedUp: string[] = [];\n\n    for (const rel of actions.markedFiles) {\n      const abs = join(cwd, rel);\n      if (!(await pathExists(abs))) {\n        continue;\n      }\n      const contents = await readFile(abs, \"utf8\").catch(() => \"\");\n      if (!contents.includes(MANAGED_MARKER)) {\n        preserved.push(rel);\n        continue;\n      }\n      if (!dryRun) {\n        await rm(abs, { force: true });\n      }\n      removed.push(rel);\n    }\n\n    for (const rel of actions.rootConfigFiles) {\n      const abs = join(cwd, rel);\n      if (!(await pathExists(abs))) {\n        continue;\n      }\n      if (!dryRun) {\n        await rm(abs, { force: true });\n      }\n      removed.push(rel);\n    }\n\n    for (const rel of actions.envBackups) {\n      const abs = join(cwd, rel);\n      if (!(await pathExists(abs))) {\n        continue;\n      }\n      if (dryRun) {\n        backedUp.push(`${rel} -> ${rel}.ejected-<timestamp>`);\n        continue;\n      }\n      const stamp = new Date().toISOString().replace(/[:.]/g, \"-\");\n      const backup = `${abs}.ejected-${stamp}`;\n      await rename(abs, backup);\n      backedUp.push(`${rel} -> ${backup.slice(cwd.length + 1)}`);\n    }\n\n    for (const rel of actions.directories) {\n      const abs = join(cwd, rel);\n      if (!(await pathExists(abs))) {\n        continue;\n      }\n      if (!dryRun) {\n        await rm(abs, { recursive: true, force: true });\n      }\n      removed.push(rel);\n    }\n\n    if (removed.length === 0 && backedUp.length === 0) {\n      return this.emit({ status: \"skipped\", reason: \"nothing-to-eject\", data: { cwd } });\n    }\n\n    const nextCommands = assembleNextCommands(backedUp, actions.dependencies);\n\n    return this.emit({\n      status: \"ok\",\n      data: {\n        title: \"Zitadel ejected. Remote project is untouched.\",\n        files_removed: removed,\n        files_preserved: preserved,\n        backed_up: backedUp,\n        next_commands: nextCommands,\n      },\n    });\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"eject.mjs","names":[],"sources":["../../src/commands/eject.ts"],"sourcesContent":["import { readFile, rename, rm, stat } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { BaseCommand, type JsonEnvelope } from \"../lib/oclif\";\nimport { ZitadelError } from \"../lib/errors\";\nimport { createOrca } from \"../lib/orca\";\nimport type { EjectActions } from \"../lib/orca/patchers/types\";\nimport { MANAGED_MARKER } from \"../lib/paths\";\nimport { readRendererId, readZitadelConfig } from \"../lib/project\";\n\n/**\n * Asks the framework patcher which artifacts it owns. Falls back to the\n * framework-agnostic set (`zitadel.json`, `.zitadel/`, `.env.local`) when the\n * framework or its patcher cannot be resolved, so an orphaned/partial project\n * can still be cleaned up.\n */\nasync function resolveEjectActions(cwd: string): Promise<EjectActions> {\n  const fallback: EjectActions = {\n    markedFiles: [],\n    rootConfigFiles: [\"zitadel.json\"],\n    directories: [\".zitadel\"],\n    envBackups: [\".env.local\"],\n    dependencies: [],\n    configEdits: [],\n  };\n  const orca = createOrca();\n  const framework = await orca.tryDetect(cwd);\n  if (!framework) {\n    return fallback;\n  }\n  try {\n    const config = await readZitadelConfig(cwd).catch(() => ({}) as Record<string, unknown>);\n    return orca.patcherFor(framework.id).artifacts({\n      framework,\n      rendererId: readRendererId(config),\n    });\n  } catch {\n    return fallback;\n  }\n}\n\n/**\n * Builds the `next_commands` envelope field — manual follow-ups `eject` can't\n * safely run itself: deleting the `.env.local.ejected-*` backups it created\n * (only when some were made), and uninstalling the SDK packages the patcher\n * added (the CLI never modifies the user's `package.json` + lockfile +\n * `node_modules` directly; it just suggests the command).\n */\nfunction assembleNextCommands(\n  backedUp: ReadonlyArray<unknown>,\n  dependencies: ReadonlyArray<string>,\n): ReadonlyArray<string> {\n  const commands: string[] = [];\n  if (backedUp.length > 0) {\n    commands.push(\"rm -f .env.local.ejected-*\");\n  }\n  for (const dep of dependencies) {\n    commands.push(`npm uninstall ${dep}`);\n  }\n  return commands;\n}\n\nasync function pathExists(path: string): Promise<boolean> {\n  try {\n    await stat(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * `zitadel eject` — remove managed files and local Zitadel state.\n *\n * Removes Zitadel-managed files from the project, leaving the remote project\n * untouched. The set of files comes from the framework patcher's\n * {@link import(\"../lib/orca/patchers/types\").Patcher.artifacts}, so the patcher\n * is the single source of truth for what its integration owns.\n *\n * Marked code files are removed only when they still carry the managed marker\n * (user-replaced files are preserved); `zitadel.json` is removed; `.env.local`\n * is renamed to a timestamped backup; and `.zitadel/` is removed wholesale.\n * `--dry-run` reports without touching the filesystem; non-interactive runs\n * require `--force`.\n */\nexport default class Eject extends BaseCommand {\n  static override description = \"Remove managed files and local Zitadel state.\";\n  static override aliases = [\"uninstall\"];\n\n  async run(): Promise<JsonEnvelope> {\n    const { flags } = await this.parse(Eject);\n    await this.toMeta(flags);\n    const { cwd, force, nonInteractive, dryRun } = this.meta;\n\n    if (!force && nonInteractive) {\n      throw new ZitadelError(\"E_VALIDATION\", \"Eject requires --force in non-interactive mode\", {\n        hint: \"Re-run with --force to confirm deletion of managed files.\",\n      });\n    }\n\n    const actions = await resolveEjectActions(cwd);\n    const removed: string[] = [];\n    const preserved: string[] = [];\n    const backedUp: string[] = [];\n\n    for (const rel of actions.markedFiles) {\n      const abs = join(cwd, rel);\n      if (!(await pathExists(abs))) {\n        continue;\n      }\n      const contents = await readFile(abs, \"utf8\").catch(() => \"\");\n      if (!contents.includes(MANAGED_MARKER)) {\n        preserved.push(rel);\n        continue;\n      }\n      if (!dryRun) {\n        await rm(abs, { force: true });\n      }\n      removed.push(rel);\n    }\n\n    for (const rel of actions.rootConfigFiles) {\n      const abs = join(cwd, rel);\n      if (!(await pathExists(abs))) {\n        continue;\n      }\n      if (!dryRun) {\n        await rm(abs, { force: true });\n      }\n      removed.push(rel);\n    }\n\n    for (const rel of actions.envBackups) {\n      const abs = join(cwd, rel);\n      if (!(await pathExists(abs))) {\n        continue;\n      }\n      if (dryRun) {\n        backedUp.push(`${rel} -> ${rel}.ejected-<timestamp>`);\n        continue;\n      }\n      const stamp = new Date().toISOString().replace(/[:.]/g, \"-\");\n      const backup = `${abs}.ejected-${stamp}`;\n      await rename(abs, backup);\n      backedUp.push(`${rel} -> ${backup.slice(cwd.length + 1)}`);\n    }\n\n    for (const rel of actions.directories) {\n      const abs = join(cwd, rel);\n      if (!(await pathExists(abs))) {\n        continue;\n      }\n      if (!dryRun) {\n        await rm(abs, { recursive: true, force: true });\n      }\n      removed.push(rel);\n    }\n\n    // In-place config merges (vite.config.ts / angular.json / nuxt.config.ts)\n    // can't be auto-reverted, so surface them as manual cleanup steps. The\n    // Angular patcher also edits package.json (a `dev` script, not a config\n    // block), so word that one accurately.\n    const manualSteps = actions.configEdits.map((rel) => {\n      if (rel === \"package.json\" || rel.endsWith(\"/package.json\")) {\n        return `Remove the \"dev\" script setup added to ${rel}`;\n      }\n      if (rel === \"angular.json\" || rel.endsWith(\"/angular.json\")) {\n        return `Remove the Zitadel proxyConfig (and dev-server port) from the serve target in ${rel}`;\n      }\n      return `Remove the Zitadel configuration block from ${rel}`;\n    });\n\n    if (removed.length === 0 && backedUp.length === 0 && manualSteps.length === 0) {\n      return this.emit({ status: \"skipped\", reason: \"nothing-to-eject\", data: { cwd } });\n    }\n\n    const nextCommands = assembleNextCommands(backedUp, actions.dependencies);\n\n    return this.emit({\n      status: \"ok\",\n      data: {\n        title: \"Zitadel ejected. Remote project is untouched.\",\n        files_removed: removed,\n        files_preserved: preserved,\n        backed_up: backedUp,\n        next_commands: nextCommands,\n        manual_steps: manualSteps,\n      },\n    });\n  }\n}\n"],"mappings":"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"}

package/dist/commands/logs.mjs

@@ -1,5 +1,5 @@
-import { E as ZitadelError, S as resolveCwd, b as publicCliCommand, h as readRuntimeMetadata, t as BaseCommand } from "../oclif-B3Qhw0cj.mjs";
-import { a as followContainerLogs, t as containerLogs } from "../docker-B4zvLujy.mjs";
+import { C as resolveCwd, D as ZitadelError, h as readRuntimeMetadata, t as BaseCommand, x as publicCliCommand } from "../oclif-2t97lHfY.mjs";
+import { a as followContainerLogs, t as containerLogs } from "../docker--EAWr_WY.mjs";
 import { Flags } from "@oclif/core";
 //#region src/commands/logs.ts
 var Logs = class Logs extends BaseCommand {

package/dist/commands/plan.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, n as summarizePlan, o as environmentSchema, r as buildSyncPlan, t as renderPlan } from "../sync-CHXZqYR7.mjs";
+import { t as BaseCommand } from "../oclif-2t97lHfY.mjs";
+import { o as readZitadelSecret } from "../project-IzPVR0Pr.mjs";
+import { a as makeSyncers, n as summarizePlan, o as environmentSchema, r as buildSyncPlan, t as renderPlan } from "../sync-Df9S8Pio.mjs";
 import { Flags } from "@oclif/core";
 import { createZitadelClient } from "@zitadel/api/client";
 import { consola as consola$1 } from "consola";

package/dist/commands/reset.mjs

@@ -1,5 +1,5 @@
-import { E as ZitadelError, S as resolveCwd, _ as removeRuntimeMetadata, b as publicCliCommand, g as removeLocalData, h as readRuntimeMetadata, p as localContainerName, t as BaseCommand } from "../oclif-B3Qhw0cj.mjs";
-import { u as stopAndRemoveContainer } from "../docker-B4zvLujy.mjs";
+import { C as resolveCwd, D as ZitadelError, _ as removeRuntimeMetadata, g as removeLocalData, h as readRuntimeMetadata, p as localContainerName, t as BaseCommand, x as publicCliCommand } from "../oclif-2t97lHfY.mjs";
+import { u as stopAndRemoveContainer } from "../docker--EAWr_WY.mjs";
 import { cancel, confirm, isCancel } from "@clack/prompts";
 //#region src/commands/reset.ts
 var Reset = class Reset extends BaseCommand {

package/dist/commands/setup.mjs

@@ -1,6 +1,6 @@
-import { D as toZitadelError, E as ZitadelError, b as publicCliCommand, n as DEFAULT_SERVER, t as BaseCommand } from "../oclif-B3Qhw0cj.mjs";
-import { n as RENDERER_IDS, r as issuerFromPort, t as createOrca } from "../orca-BGM8VCgQ.mjs";
-import { n as hasZitadelSecret, t as hasZitadelConfig } from "../project-kWWyS7fS.mjs";
+import { D as ZitadelError, O as toZitadelError, n as DEFAULT_SERVER, t as BaseCommand, x as publicCliCommand } from "../oclif-2t97lHfY.mjs";
+import { n as RENDERER_IDS, r as issuerFromPort, t as createOrca } from "../orca-CYqJP4ZJ.mjs";
+import { n as hasZitadelSecret, t as hasZitadelConfig } from "../project-IzPVR0Pr.mjs";
 import { cancel, confirm, intro, isCancel, outro, select, spinner, text } from "@clack/prompts";
 import { Flags } from "@oclif/core";
 import { createZitadelClient } from "@zitadel/api/client";
@@ -141,11 +141,16 @@ async function installDependenciesForSetup(input) {
 	});
 }
 function outcome(input) {
-	const startAction = `Start your project: ${input.devCommand} (then open ${input.issuer}/login)`;
+	const startAction = `Start your project: ${input.devCommand} (then open ${input.issuer})`;
+	const verifyAction = "Verify auth in the browser: register a user, log out, log in again with the same user, and confirm /profile shows Signed in.";
 	return {
 		install: input.install,
 		devCommand: input.devCommand,
-		nextActions: input.includeInstallCommand ? [`Install dependencies: ${input.install.command}`, startAction] : [startAction],
+		nextActions: input.includeInstallCommand ? [
+			`Install dependencies: ${input.install.command}`,
+			startAction,
+			verifyAction
+		] : [startAction, verifyAction],
 		nextCommands: input.includeInstallCommand ? [input.install.command, input.devCommand] : [input.devCommand]
 	};
 }
@@ -188,7 +193,8 @@ function bail(value) {
 * becomes the issuer URL (`http://localhost:<port>`) via `issuerFromPort`.
 */
 var DevPortPrompt = class {
-	async ask(answers, _ctx) {
+	async ask(answers, ctx) {
+		if (ctx.devPortFromFlag) return answers;
 		const value = await text({
 			message: "Dev server port",
 			placeholder: String(answers.devPort),
@@ -587,7 +593,7 @@ const FRAMEWORK_OPTIONS = createOrca().availableFrameworks().map((framework) =>
 */
 var Setup = class Setup extends BaseCommand {
 	static description = "Create a Zitadel project and scaffold local auth.";
-	static examples = ["<%= config.bin %> setup --framework next"];
+	static examples = ["<%= config.bin %> setup --framework next", "<%= config.bin %> setup --framework react --dev-port 3000"];
 	static flags = {
 		framework: Flags.string({
 			description: "Framework to target.",
@@ -597,11 +603,16 @@ var Setup = class Setup extends BaseCommand {
 			description: "Renderer (default: react).",
 			options: [...RENDERER_IDS]
 		}),
+		"dev-port": Flags.integer({ description: "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." }),
 		"skip-install": Flags.boolean({ description: "Do not install dependencies after setup updates package.json." })
 	};
 	async run() {
 		const { flags } = await this.parse(Setup);
-		await this.toMeta(flags);
+		try {
+			await this.toMeta(flags);
+		} catch (error) {
+			throw localSetupHint(error, flags.framework, this.config.version);
+		}
 		const { cwd, nonInteractive, dryRun, force } = this.meta;
 		if (await hasZitadelConfig(cwd)) return this.emit({
 			status: "skipped",
@@ -623,6 +634,15 @@ var Setup = class Setup extends BaseCommand {
 				consola$1.success(`Scaffolded ${framework.id} skeleton`);
 			} else throw error;
 		}
+		if (flags["dev-port"] !== void 0) {
+			const devPort = flags["dev-port"];
+			if (!Number.isInteger(devPort) || devPort < 1 || devPort > 65535) throw new ZitadelError("E_VALIDATION", `--dev-port must be an integer in 1..65535, got ${devPort}`);
+			framework = {
+				...framework,
+				devPort,
+				url: issuerFromPort(devPort)
+			};
+		}
 		let answers = {
 			server: this.meta.source,
 			devPort: framework.devPort
@@ -631,15 +651,21 @@ var Setup = class Setup extends BaseCommand {
 			intro("Zitadel setup");
 			const promptCtx = {
 				framework,
-				serverFlag: this.meta.serverFlag
+				serverFlag: this.meta.serverFlag,
+				devPortFromFlag: flags["dev-port"] !== void 0
 			};
 			for (const prompt of SETUP_PROMPTS) answers = await prompt.ask(answers, promptCtx);
 			outro("Configuration captured");
 		}
 		const issuer = issuerFromPort(answers.devPort);
+		framework = {
+			...framework,
+			devPort: answers.devPort,
+			url: issuer
+		};
 		consola$1.start(`Creating project on ${answers.server}${dryRun ? " (dry run)" : ""}`);
 		const unauthClient = createZitadelClient({ baseUrl: answers.server });
-		const project = dryRun ? dryRunProject() : await createProjectWithLocalHint(unauthClient, answers.server, this.meta.cliVersion);
+		const project = dryRun ? dryRunProject(issuer) : await createProjectWithLocalHint(unauthClient, answers.server, this.meta.cliVersion, issuer, framework.id);
 		consola$1.success(`Created project ${project.id}`);
 		const ctx = {
 			framework,
@@ -647,7 +673,8 @@ var Setup = class Setup extends BaseCommand {
 			project,
 			issuer,
 			server: answers.server,
-			cliVersion: this.meta.cliVersion
+			cliVersion: this.meta.cliVersion,
+			scaffoldedFramework
 		};
 		consola$1.start(`Patching project files${dryRun ? " (dry run)" : ""}`);
 		const result = await orca.patcherFor(framework.id).patch(ctx, {
@@ -726,23 +753,23 @@ async function resolveScaffoldFramework(framework, nonInteractive, orca) {
 	return new PickFrameworkPrompt().ask(orca.availableFrameworks());
 }
 /** A deterministic stand-in project for `--dry-run`, so no remote call is made. */
-function dryRunProject() {
+function dryRunProject(issuer) {
 	return {
 		id: "dry-run-0000",
 		projectSecret: "sk_proj_dry_run_full",
 		previewSecret: "sk_proj_dry_run_preview",
-		previewOrigins: [],
+		previewOrigins: [issuer],
 		createdAt: "2026-04-21T14:03:11.000Z"
 	};
 }
-async function createProjectWithLocalHint(client, server, cliVersion) {
+async function createProjectWithLocalHint(client, server, cliVersion, issuer, framework) {
 	try {
-		return await client.createProject({ previewOrigins: [] });
+		return await client.createProject({ previewOrigins: [issuer] });
 	} catch (error) {
 		const normalized = toZitadelError(error);
 		throw new ZitadelError(normalized.code, normalized.message, {
-			hint: `${normalized.hint ? `${normalized.hint} ` : ""}If you meant to use a local Zitadel server, run npx @zitadel/cli@alpha start and retry setup with --server local.`,
-			nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand("setup --server local", cliVersion)],
+			hint: `${normalized.hint ? `${normalized.hint} ` : ""}If you meant to use a local Zitadel server, start it first and retry setup with --framework ${framework} --server local.`,
+			nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand(`setup --framework ${framework} --server local`, cliVersion)],
 			details: {
 				server,
 				original: normalized.details
@@ -750,6 +777,16 @@ async function createProjectWithLocalHint(client, server, cliVersion) {
 		});
 	}
 }
+function localSetupHint(error, framework, cliVersion) {
+	const normalized = toZitadelError(error);
+	if (normalized.code !== "E_LOCAL_SERVER_NOT_RUNNING") return error;
+	const setupCommand = framework ? `setup --framework ${framework} --server local` : "setup --server local";
+	return new ZitadelError(normalized.code, normalized.message, {
+		hint: `${normalized.hint ? `${normalized.hint} ` : ""}Start local Zitadel first, then rerun setup. After setup succeeds, follow its next_commands to start the app and verify registration, logout, and login in the browser.`,
+		nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand(setupCommand, cliVersion)],
+		details: normalized.details
+	});
+}
 /** Renders an absolute path relative to `cwd` for human-readable output. */
 function relativeDisplay(cwd, path) {
 	return path.startsWith(cwd) ? path.slice(cwd.length + 1) : path;
@@ -801,6 +838,7 @@ const SENTENCE_BY_PATH = {
 	".env.example": { subject: "the .env example template" },
 	".env.local": { subject: "the local development environment variables" },
 	".zitadel/state.json": { subject: "the empty sync state file" },
+	"app/page.tsx": { subject: "the auth home page" },
 	"app/login/page.tsx": { subject: "the login page" },
 	"app/register/page.tsx": { subject: "the registration page" },
 	"app/profile/page.tsx": { subject: "the profile page" },
@@ -829,6 +867,7 @@ function buildSummary(opts) {
 		secondary: path(fileNameOf(packageJsonHit))
 	});
 	for (const [label, suffix] of [
+		["Home page", "app/page.tsx"],
 		["Login page", "app/login/page.tsx"],
 		["Register page", "app/register/page.tsx"],
 		["Profile page", "app/profile/page.tsx"],