@zitadel/cli 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -3,7 +3,8 @@
 Scaffolds Zitadel auth (login, register, profile, middleware) into a Next.js app.
 
 ```sh
-npx @zitadel/cli@latest setup --framework next --server <your-zitadel-server>
+npx @zitadel/cli@alpha start
+npx @zitadel/cli@alpha setup --framework next --server local
 ```
 
 > **Beta.** This is the **next-generation Zitadel**, a ground-up rewrite of the platform. It is distinct from the established Zitadel at [github.com/zitadel/zitadel](https://github.com/zitadel/zitadel). APIs and CLI flags will change.
@@ -11,21 +12,41 @@ npx @zitadel/cli@latest setup --framework next --server <your-zitadel-server>
 ## Requirements
 
 - Node 20+
+- Docker for the managed local Zitadel runtime
 - A Next.js project created with `create-next-app`
-- A running next-generation Zitadel server to point at:
-  - **Zitadel Cloud** — coming soon
-  - **Self-hosted** — grab a binary from [github.com/zitadel/nextgen/releases](https://github.com/zitadel/nextgen/releases) and run it locally
 
 ## Quickstart
 
 ```sh
 npx create-next-app@latest my-app
 cd my-app
-npx @zitadel/cli@latest setup --framework next --server http://localhost:8080
+npx @zitadel/cli@alpha doctor
+npx @zitadel/cli@alpha start
+npx @zitadel/cli@alpha setup --framework next --server local
 npm run dev
 ```
 
-`setup` creates a project on the Zitadel server, scaffolds `app/login`, `app/register`, `app/profile`, and `middleware.ts`, and writes `.env.local` and `.zitadel/`. 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.
+`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.
+`setup --server local` creates a project on that local server, scaffolds
+`app/login`, `app/register`, and `middleware.ts`, 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.
+
+For a reproducible tester report, use the exact alpha train from the GitHub
+Release:
+
+```sh
+npx @zitadel/cli@0.1.0-alpha.N doctor
+npx @zitadel/cli@0.1.0-alpha.N start
+npx @zitadel/cli@0.1.0-alpha.N setup --framework next --server local
+```
 
 The default project flow supports password registration/login, passkey
 registration/login, and optional passkey setup after password registration.
@@ -34,9 +55,10 @@ passkey can sign in with either credential.
 
 ## Other commands
 
-- `zitadel doctor` — verify the generated files and local state
-- `zitadel status` — summarise the local project
+- `zitadel doctor` — verify the local Docker runtime and generated project files
+- `zitadel status` — summarise the local Docker runtime and project
 - `zitadel eject` — remove what setup wrote (alias: `zitadel uninstall`)
+- `zitadel start|stop|logs|reset` — manage the local Docker runtime
 
 ## Reference
 
@@ -44,17 +66,22 @@ passkey can sign in with either credential.
 <summary>Full command reference</summary>
 
 <!-- commands -->
-* [`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 search`](#zitadel-search)
-* [`zitadel setup`](#zitadel-setup)
-* [`zitadel status`](#zitadel-status)
-* [`zitadel uninstall`](#zitadel-uninstall)
-* [`zitadel version`](#zitadel-version)
-* [`zitadel which`](#zitadel-which)
+
+- [`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 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 autocomplete [SHELL]`
 
@@ -118,11 +145,12 @@ _See code: [@oclif/plugin-commands](https://github.com/oclif/plugin-commands/blo
 
 ## `zitadel doctor`
 
-Verify generated files and local state.
+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>]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -132,13 +160,15 @@ FLAGS
       --debug            Debug logging.
       --dry-run          Preview without mutating files or the platform.
       --fix              Re-apply missing managed files.
+      --image=<value>    Container image to check.
+      --port=<value>     [default: 8080] Local HTTP port.
       --verbose          Verbose logging.
 
 GLOBAL FLAGS
   --json  Format output as json.
 
 DESCRIPTION
-  Verify generated files and local state.
+  Verify local runtime and project state.
 ```
 
 ## `zitadel eject`
@@ -188,6 +218,57 @@ DESCRIPTION
 
 _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/6.2.49/src/commands/help.ts)_
 
+## `zitadel logs`
+
+Show local Zitadel server logs.
+
+```
+USAGE
+  $ zitadel logs [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [--follow]
+    [--tail <value>]
+
+FLAGS
+  -c, --cwd=<value>      Project directory to operate on.
+  -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.
+      --follow           Follow logs.
+      --tail=<value>     [default: 200] Number of lines to show.
+      --verbose          Verbose logging.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Show local Zitadel server logs.
+```
+
+## `zitadel reset`
+
+Delete the local Zitadel server runtime and data.
+
+```
+USAGE
+  $ zitadel reset [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+
+FLAGS
+  -c, --cwd=<value>      Project directory to operate on.
+  -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.
+
+DESCRIPTION
+  Delete the local Zitadel server runtime and data.
+```
+
 ## `zitadel search`
 
 Search for a command.
@@ -211,7 +292,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]
+    [--framework next] [--renderer react|web-component] [--skip-install]
 
 FLAGS
   -c, --cwd=<value>         Project directory to operate on.
@@ -224,6 +305,7 @@ FLAGS
                             <options: next>
       --renderer=<option>   Renderer (default: react).
                             <options: react|web-component>
+      --skip-install        Do not install dependencies after setup updates package.json.
       --verbose             Verbose logging.
 
 GLOBAL FLAGS
@@ -236,9 +318,36 @@ EXAMPLES
   $ zitadel setup --framework next
 ```
 
+## `zitadel start`
+
+Start a local Zitadel server.
+
+```
+USAGE
+  $ zitadel start [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [--image
+    <value>] [--port <value>]
+
+FLAGS
+  -c, --cwd=<value>      Project directory to operate on.
+  -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.
+      --image=<value>    Container image to run.
+      --port=<value>     [default: 8080] Local HTTP port.
+      --verbose          Verbose logging.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Start a local Zitadel server.
+```
+
 ## `zitadel status`
 
-Summarize the local project state.
+Summarize the local Zitadel server and project state.
 
 ```
 USAGE
@@ -257,7 +366,31 @@ GLOBAL FLAGS
   --json  Format output as json.
 
 DESCRIPTION
-  Summarize the local project state.
+  Summarize the local Zitadel server and project state.
+```
+
+## `zitadel stop`
+
+Stop the local Zitadel server.
+
+```
+USAGE
+  $ zitadel stop [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+
+FLAGS
+  -c, --cwd=<value>      Project directory to operate on.
+  -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.
+
+DESCRIPTION
+  Stop the local Zitadel server.
 ```
 
 ## `zitadel uninstall`
@@ -340,6 +473,7 @@ 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

@@ -24,7 +24,7 @@ parse the result rather than scraping human output.
   metadata) or run `zitadel <command> --help` for the full per-command flag list.
 
 ```sh
-npx @zitadel/cli@latest <command> --non-interactive --json
+npx @zitadel/cli@alpha <command> --non-interactive --json
 ```
 
 ## Reading the envelope
@@ -38,6 +38,8 @@ 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
+  `npx @zitadel/cli@alpha start`, then retry with `--server local`.
 
 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
@@ -51,21 +53,51 @@ layer, not the envelope.
   scaffolds nor uploads them. Flags: `--framework`, `--renderer`.
 - `plan` — validate config and preview the sync diff without mutating anything.
 - `apply` — validate and upload repo config to the platform.
-- `doctor` — verify generated files and local state; `--fix` re-applies missing
-  managed files.
-- `status` — summarize the local project state.
+- `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.
 - `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;
+  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.
 
 ## Golden path
 
 ```sh
-npx @zitadel/cli@latest setup --framework next --non-interactive --json
-npx @zitadel/cli@latest doctor --non-interactive --json
-npx @zitadel/cli@latest plan --non-interactive --json
-npx @zitadel/cli@latest apply --non-interactive --json
+npx @zitadel/cli@alpha doctor --non-interactive --json
+npx @zitadel/cli@alpha start --non-interactive --json
+npx @zitadel/cli@alpha setup --framework next --server local --non-interactive --json
+npx @zitadel/cli@alpha doctor --non-interactive --json
+npx @zitadel/cli@alpha plan --non-interactive --json
+npx @zitadel/cli@alpha apply --non-interactive --json
+```
+
+Exact alpha train invocation:
+
+```sh
+npx @zitadel/cli@0.1.0-alpha.N doctor --non-interactive --json
+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
 ```
 
 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.
+For app-local development, `--server local` resolves through
+`.zitadel/local/runtime.json` and requires a healthy `npx @zitadel/cli@alpha start`
+runtime. `setup` installs dependencies with the detected package manager by
+default; pass `--skip-install` when the agent or host workflow will install
+dependencies separately.

package/dist/commands/apply.mjs

@@ -1,8 +1,9 @@
-import { o as readZitadelSecret, s as BaseCommand } from "../project-C3pSfbao.mjs";
-import { a as makeSyncers, i as runSyncLoop, n as summarizePlan, o as environmentSchema, r as buildSyncPlan, t as renderPlan } from "../sync-Cuyh-X1J.mjs";
+import { t as BaseCommand } from "../oclif-CqkWBQ7i.mjs";
+import { o as readZitadelSecret } from "../project-B6YfSaZw.mjs";
+import { a as makeSyncers, i as runSyncLoop, n as summarizePlan, o as environmentSchema, r as buildSyncPlan, t as renderPlan } from "../sync-DN4oNLVH.mjs";
 import { Flags } from "@oclif/core";
-import { consola as consola$1 } from "consola";
 import { createZitadelClient } from "@zitadel/api/client";
+import { consola as consola$1 } from "consola";
 //#region src/commands/apply.ts
 /**
 * `zitadel apply` — validate and upload repo config to the platform.

package/dist/commands/apply.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"apply.mjs","names":[],"sources":["../../src/commands/apply.ts"],"sourcesContent":["import { Flags } from \"@oclif/core\";\nimport { consola } from \"consola\";\n\nimport { createZitadelClient } from \"@zitadel/api/client\";\n\nimport { BaseCommand, type JsonEnvelope } from \"../lib/oclif\";\nimport { environmentSchema } from \"../lib/environment\";\nimport { buildSyncPlan, makeSyncers, renderPlan, runSyncLoop, summarizePlan } from \"../lib/sync\";\nimport { readZitadelSecret } from \"../lib/project\";\n\n/**\n * `zitadel apply` — validate and upload repo config to the platform.\n *\n * Runs the sync loop to convergence, or (with `--dry-run`) previews the diff\n * without mutating. All validation — structural shape and `${VAR}` / `*_env`\n * reference presence — happens inside the sync engine ({@link buildSyncPlan}),\n * so an invalid or under-configured file fails with `E_VALIDATION` before any\n * platform call.\n */\nexport default class Apply extends BaseCommand {\n  static override description = \"Validate and upload repo config to the platform.\";\n  // Temporarily hidden while we collapse the dev workflow around `setup`'s\n  // auto-apply. The logic stays wired up so re-exposing this command is a\n  // one-line flip when we settle on the surface area.\n  static override hidden = true;\n  static override flags = {\n    environment: Flags.string({\n      char: \"e\",\n      description: \"Target environment (default: development).\",\n      options: [...environmentSchema.options],\n    }),\n  };\n\n  async run(): Promise<JsonEnvelope> {\n    const { flags } = await this.parse(Apply);\n    await this.toMeta(flags);\n    const { cwd, source, env, dryRun, isTTY } = this.meta;\n\n    const secret = await readZitadelSecret(cwd);\n    consola.info(`Project   ${secret.project_id}`);\n    consola.info(`Server    ${source}`);\n    const client = createZitadelClient({\n      baseUrl: source,\n      token: secret.project_secret,\n    });\n    const syncers = makeSyncers({ client, projectId: secret.project_id, env });\n\n    if (!dryRun) {\n      consola.start(\"Syncing schemas and flows to Zitadel\");\n      await runSyncLoop(cwd, syncers);\n      consola.success(\"Sync complete\");\n      return this.emit({ status: \"ok\", data: { synced: true } });\n    }\n\n    consola.start(\"Building plan (dry run)\");\n    const plan = await buildSyncPlan(cwd, syncers, true);\n    const summary = summarizePlan(plan);\n    consola.success(\n      `Plan: ${summary.creates} create${summary.creates === 1 ? \"\" : \"s\"}, ` +\n        `${summary.updates} update${summary.updates === 1 ? \"\" : \"s\"}, ` +\n        `${summary.deletes} delete${summary.deletes === 1 ? \"\" : \"s\"}`,\n    );\n    return this.emit({\n      status: \"ok\",\n      data: summary,\n      pretty: renderPlan(plan, isTTY),\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAmBA,IAAqB,QAArB,MAAqB,cAAc,YAAY;CAC7C,OAAgB,cAAc;CAI9B,OAAgB,SAAS;CACzB,OAAgB,QAAQ,EACtB,aAAa,MAAM,OAAO;EACxB,MAAM;EACN,aAAa;EACb,SAAS,CAAC,GAAG,kBAAkB,QAAQ;EACxC,CAAC,EACH;CAED,MAAM,MAA6B;EACjC,MAAM,EAAE,UAAU,MAAM,KAAK,MAAM,MAAM;AACzC,QAAM,KAAK,OAAO,MAAM;EACxB,MAAM,EAAE,KAAK,QAAQ,KAAK,QAAQ,UAAU,KAAK;EAEjD,MAAM,SAAS,MAAM,kBAAkB,IAAI;AAC3C,YAAQ,KAAK,aAAa,OAAO,aAAa;AAC9C,YAAQ,KAAK,aAAa,SAAS;EAKnC,MAAM,UAAU,YAAY;GAAE,QAJf,oBAAoB;IACjC,SAAS;IACT,OAAO,OAAO;IACf,CACmC;GAAE,WAAW,OAAO;GAAY;GAAK,CAAC;AAE1E,MAAI,CAAC,QAAQ;AACX,aAAQ,MAAM,uCAAuC;AACrD,SAAM,YAAY,KAAK,QAAQ;AAC/B,aAAQ,QAAQ,gBAAgB;AAChC,UAAO,KAAK,KAAK;IAAE,QAAQ;IAAM,MAAM,EAAE,QAAQ,MAAM;IAAE,CAAC;;AAG5D,YAAQ,MAAM,0BAA0B;EACxC,MAAM,OAAO,MAAM,cAAc,KAAK,SAAS,KAAK;EACpD,MAAM,UAAU,cAAc,KAAK;AACnC,YAAQ,QACN,SAAS,QAAQ,QAAQ,SAAS,QAAQ,YAAY,IAAI,KAAK,IAAI,IAC9D,QAAQ,QAAQ,SAAS,QAAQ,YAAY,IAAI,KAAK,IAAI,IAC1D,QAAQ,QAAQ,SAAS,QAAQ,YAAY,IAAI,KAAK,MAC5D;AACD,SAAO,KAAK,KAAK;GACf,QAAQ;GACR,MAAM;GACN,QAAQ,WAAW,MAAM,MAAM;GAChC,CAAC"}
+{"version":3,"file":"apply.mjs","names":[],"sources":["../../src/commands/apply.ts"],"sourcesContent":["import { Flags } from \"@oclif/core\";\nimport { consola } from \"consola\";\n\nimport { createZitadelClient } from \"@zitadel/api/client\";\n\nimport { BaseCommand, type JsonEnvelope } from \"../lib/oclif\";\nimport { environmentSchema } from \"../lib/environment\";\nimport { buildSyncPlan, makeSyncers, renderPlan, runSyncLoop, summarizePlan } from \"../lib/sync\";\nimport { readZitadelSecret } from \"../lib/project\";\n\n/**\n * `zitadel apply` — validate and upload repo config to the platform.\n *\n * Runs the sync loop to convergence, or (with `--dry-run`) previews the diff\n * without mutating. All validation — structural shape and `${VAR}` / `*_env`\n * reference presence — happens inside the sync engine ({@link buildSyncPlan}),\n * so an invalid or under-configured file fails with `E_VALIDATION` before any\n * platform call.\n */\nexport default class Apply extends BaseCommand {\n  static override description = \"Validate and upload repo config to the platform.\";\n  // Temporarily hidden while we collapse the dev workflow around `setup`'s\n  // auto-apply. The logic stays wired up so re-exposing this command is a\n  // one-line flip when we settle on the surface area.\n  static override hidden = true;\n  static override flags = {\n    environment: Flags.string({\n      char: \"e\",\n      description: \"Target environment (default: development).\",\n      options: [...environmentSchema.options],\n    }),\n  };\n\n  async run(): Promise<JsonEnvelope> {\n    const { flags } = await this.parse(Apply);\n    await this.toMeta(flags);\n    const { cwd, source, env, dryRun, isTTY } = this.meta;\n\n    const secret = await readZitadelSecret(cwd);\n    consola.info(`Project   ${secret.project_id}`);\n    consola.info(`Server    ${source}`);\n    const client = createZitadelClient({\n      baseUrl: source,\n      token: secret.project_secret,\n    });\n    const syncers = makeSyncers({ client, projectId: secret.project_id, env });\n\n    if (!dryRun) {\n      consola.start(\"Syncing schemas and flows to Zitadel\");\n      await runSyncLoop(cwd, syncers);\n      consola.success(\"Sync complete\");\n      return this.emit({ status: \"ok\", data: { synced: true } });\n    }\n\n    consola.start(\"Building plan (dry run)\");\n    const plan = await buildSyncPlan(cwd, syncers, true);\n    const summary = summarizePlan(plan);\n    consola.success(\n      `Plan: ${summary.creates} create${summary.creates === 1 ? \"\" : \"s\"}, ` +\n        `${summary.updates} update${summary.updates === 1 ? \"\" : \"s\"}, ` +\n        `${summary.deletes} delete${summary.deletes === 1 ? \"\" : \"s\"}`,\n    );\n    return this.emit({\n      status: \"ok\",\n      data: summary,\n      pretty: renderPlan(plan, isTTY),\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAmBA,IAAqB,QAArB,MAAqB,cAAc,YAAY;CAC7C,OAAgB,cAAc;CAI9B,OAAgB,SAAS;CACzB,OAAgB,QAAQ,EACtB,aAAa,MAAM,OAAO;EACxB,MAAM;EACN,aAAa;EACb,SAAS,CAAC,GAAG,kBAAkB,QAAQ;EACxC,CAAC,EACH;CAED,MAAM,MAA6B;EACjC,MAAM,EAAE,UAAU,MAAM,KAAK,MAAM,MAAM;AACzC,QAAM,KAAK,OAAO,MAAM;EACxB,MAAM,EAAE,KAAK,QAAQ,KAAK,QAAQ,UAAU,KAAK;EAEjD,MAAM,SAAS,MAAM,kBAAkB,IAAI;AAC3C,YAAQ,KAAK,aAAa,OAAO,aAAa;AAC9C,YAAQ,KAAK,aAAa,SAAS;EAKnC,MAAM,UAAU,YAAY;GAAE,QAJf,oBAAoB;IACjC,SAAS;IACT,OAAO,OAAO;IACf,CACmC;GAAE,WAAW,OAAO;GAAY;GAAK,CAAC;AAE1E,MAAI,CAAC,QAAQ;AACX,aAAQ,MAAM,uCAAuC;AACrD,SAAM,YAAY,KAAK,QAAQ;AAC/B,aAAQ,QAAQ,gBAAgB;AAChC,UAAO,KAAK,KAAK;IAAE,QAAQ;IAAM,MAAM,EAAE,QAAQ,MAAM;IAAE,CAAC;;AAG5D,YAAQ,MAAM,0BAA0B;EACxC,MAAM,OAAO,MAAM,cAAc,KAAK,SAAS,KAAK;EACpD,MAAM,UAAU,cAAc,KAAK;AACnC,YAAQ,QACN,SAAS,QAAQ,QAAQ,SAAS,QAAQ,YAAY,IAAI,KAAK,IAAI,IAC9D,QAAQ,QAAQ,SAAS,QAAQ,YAAY,IAAI,KAAK,IAAI,IAC1D,QAAQ,QAAQ,SAAS,QAAQ,YAAY,IAAI,KAAK,MAC5D;AACD,SAAO,KAAK,KAAK;GACf,QAAQ;GACR,MAAM;GACN,QAAQ,WAAW,MAAM,MAAM;GAChC,CAAC"}

package/dist/commands/doctor.mjs

@@ -1,9 +1,11 @@
-import { a as readZitadelConfig, i as readRendererId, o as readZitadelSecret, p as ZitadelError, r as readDevelopmentIssuer, s as BaseCommand, u as isObject } from "../project-C3pSfbao.mjs";
-import { r as issuerFromPort, t as createOrca } from "../orca-COsUnVoz.mjs";
+import { C as isObject, E as ZitadelError, a as DEFAULT_LOCAL_SERVER_PORT, c as checkLocalServerHealth, f as isPortAvailable, g as readRuntimeMetadata, h as localServerUrl, l as defaultLocalServerImageForCliVersion, m as localRuntimePaths, s as assertWritableDirectory, t as BaseCommand, x as publicCliCommand } from "../oclif-CqkWBQ7i.mjs";
+import { r as issuerFromPort, t as createOrca } from "../orca-S1tVnngd.mjs";
+import { a as readZitadelConfig, i as readRendererId, o as readZitadelSecret, r as readDevelopmentIssuer, t as hasZitadelConfig } from "../project-B6YfSaZw.mjs";
+import { o as imageAvailable, r as dockerAvailable } from "../docker-DrOBycgG.mjs";
 import { Flags } from "@oclif/core";
 import consola from "consola";
-import { chmod, readFile, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { chmod, readFile, stat, writeFile } from "node:fs/promises";
 import "@zitadel/api/generated/endpoints/zitadelNextGen.zod";
 //#region src/commands/doctor/checks/types.ts
 /**
@@ -148,7 +150,7 @@ var FrameworkCheck = class extends AbstractSanityCheck {
 * SDK package via `patcher.repair`. The user schema and flow definition are
 * server-owned and no longer scaffolded locally, so nothing here reads them.
 */
-async function loadPatchContext(cwd, orca) {
+async function loadPatchContext(cwd, orca, cliVersion) {
 	const config = await readZitadelConfig(cwd);
 	const secret = await readZitadelSecret(cwd);
 	const framework = await orca.detect(cwd);
@@ -157,6 +159,7 @@ async function loadPatchContext(cwd, orca) {
 		rendererId: readRendererId(config),
 		issuer: await resolveIssuer(cwd, config, framework),
 		server: typeof config.server === "string" ? config.server : "",
+		cliVersion,
 		project: {
 			id: secret.project_id,
 			projectSecret: secret.project_secret,
@@ -206,7 +209,7 @@ var DependencyCheck = class extends AbstractSanityCheck {
 	* so going through `repair` is the only sanctioned path.
 	*/
 	async fix(ctx) {
-		const patchCtx = await loadPatchContext(ctx.cwd, ctx.orca);
+		const patchCtx = await loadPatchContext(ctx.cwd, ctx.orca, ctx.cliVersion);
 		await ctx.orca.patcherFor(patchCtx.framework.id).repair(patchCtx, {
 			cwd: ctx.cwd,
 			dryRun: ctx.dryRun,
@@ -243,6 +246,13 @@ const SANITY_CHECKS = [
 ];
 //#endregion
 //#region src/commands/doctor/index.ts
+const LOCAL_RUNTIME_CHECK_NAMES = new Set([
+	"docker-cli",
+	"image",
+	"state-dir",
+	"port",
+	"runtime"
+]);
 /**
 * `zitadel doctor` — verify generated files and local state.
 *
@@ -257,18 +267,33 @@ const SANITY_CHECKS = [
 * whatever remains broken.
 */
 var Doctor = class Doctor extends BaseCommand {
-	static description = "Verify generated files and local state.";
-	static flags = { fix: Flags.boolean({ description: "Re-apply missing managed files." }) };
+	static description = "Verify local runtime and project state.";
+	static flags = {
+		fix: Flags.boolean({ description: "Re-apply missing managed files." }),
+		image: Flags.string({ description: "Container image to check." }),
+		port: Flags.integer({
+			description: "Local HTTP port.",
+			default: DEFAULT_LOCAL_SERVER_PORT
+		})
+	};
 	async run() {
 		const { flags } = await this.parse(Doctor);
-		await this.toMeta(flags);
+		const port = flags.port ?? 8080;
+		await this.toMeta(flags, {
+			resolveServer: false,
+			source: localServerUrl(port)
+		});
 		const { cwd, dryRun } = this.meta;
+		const image = flags.image ?? this.meta.env.ZITADEL_LOCAL_IMAGE ?? defaultLocalServerImageForCliVersion(this.meta.cliVersion);
+		const runtimeChecks = await runLocalRuntimeChecks(cwd, image, port);
+		const hasConfig = await hasZitadelConfig(cwd);
 		const ctx = {
 			cwd,
 			orca: createOrca(),
+			cliVersion: this.meta.cliVersion,
 			dryRun
 		};
-		if (flags.fix) {
+		if (hasConfig && flags.fix) {
 			const before = await Promise.all(SANITY_CHECKS.map((check) => check.run(ctx)));
 			for (const [index, check] of SANITY_CHECKS.entries()) {
 				if (before[index]?.status !== "fail") continue;
@@ -279,23 +304,132 @@ var Doctor = class Doctor extends BaseCommand {
 				}
 			}
 		}
-		const checks = await Promise.all(SANITY_CHECKS.map((check) => check.run(ctx)));
+		const projectChecks = hasConfig ? await Promise.all(SANITY_CHECKS.map((check) => check.run(ctx))) : [];
+		const checks = [...runtimeChecks, ...projectChecks];
 		const failed = checks.filter((check) => check.status === "fail");
+		const warnings = checks.filter((check) => check.status === "warn");
 		const data = {
-			title: failed.length === 0 ? "Zitadel doctor passed." : "Zitadel doctor found issues.",
+			title: failed.length > 0 ? "Zitadel doctor found issues." : warnings.length > 0 ? "Zitadel doctor passed with warnings." : "Zitadel doctor passed.",
 			ok: failed.length === 0,
+			image,
+			port,
+			project: { lifecycle: hasConfig ? "configured" : "not-configured" },
 			checks
 		};
-		if (failed.length > 0) throw new ZitadelError("E_VALIDATION", "Zitadel doctor found issues", {
-			hint: "Run `npx @zitadel/cli@latest doctor --fix` to re-apply missing managed files.",
-			details: data
-		});
+		if (failed.length > 0) {
+			const advice = failureAdvice(failed, image, port, this.meta.cliVersion);
+			throw new ZitadelError("E_VALIDATION", "Zitadel doctor found issues", {
+				hint: advice.hint,
+				nextCommands: advice.nextCommands,
+				details: data
+			});
+		}
 		return this.emit({
 			status: "ok",
-			data
+			data,
+			warnings: warnings.map((warning) => `${warning.name}: ${warning.message}`)
 		});
 	}
 };
+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("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)]
+	};
+	if (failedNames.has("state-dir")) return {
+		hint: "The local Zitadel state directory is not writable. Fix directory permissions, then rerun `zitadel doctor`.",
+		nextCommands: [publicCliCommand("doctor", cliVersion)]
+	};
+	if (failedNames.has("port")) {
+		const fallbackPort = port === 8080 ? port + 1 : DEFAULT_LOCAL_SERVER_PORT;
+		return {
+			hint: `Port ${String(port)} is already in use. Stop the process using it, or choose another port for local Zitadel.`,
+			nextCommands: [publicCliCommand(`doctor --port ${String(fallbackPort)}`, cliVersion)]
+		};
+	}
+	if (failedNames.has("runtime")) return {
+		hint: "Existing local runtime metadata was found, but the local Zitadel server is not healthy. Start it again or reset stale local data.",
+		nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand("reset --force", cliVersion)]
+	};
+	if (failed.some((check) => !LOCAL_RUNTIME_CHECK_NAMES.has(check.name))) return {
+		hint: `Run \`${publicCliCommand("doctor --fix", cliVersion)}\` to re-apply missing managed files.`,
+		nextCommands: [publicCliCommand("doctor --fix", cliVersion)]
+	};
+	return {
+		hint: "Fix the reported checks, then rerun `zitadel doctor`.",
+		nextCommands: [publicCliCommand("doctor", cliVersion)]
+	};
+}
+async function runLocalRuntimeChecks(cwd, image, port) {
+	const runtime = await readRuntimeMetadata(cwd);
+	const docker = await check("docker-cli", "Docker is reachable", async () => {
+		let result;
+		try {
+			result = await dockerAvailable();
+		} catch (error) {
+			throw new Error(dockerUnavailableMessage(error), { cause: error });
+		}
+		if (result.status !== 0) throw new Error(dockerUnavailableMessage(result.stderr || "docker version failed"));
+		return `Docker engine ${result.stdout.trim() || "available"}`;
+	}, "warn");
+	return [
+		docker,
+		docker.status === "pass" ? await check("image", `Image ${image} is available`, async () => {
+			try {
+				return await imageAvailable(image) === "local" ? `Image ${image} is available locally` : `Image ${image} is available from the registry`;
+			} catch (error) {
+				throw new Error(imageUnavailableMessage(image, error), { cause: error });
+			}
+		}, "warn") : {
+			name: "image",
+			status: "warn",
+			message: "Skipped image check because Docker is not reachable."
+		},
+		await check("state-dir", "Local state directory is writable", async () => {
+			const paths = localRuntimePaths(cwd);
+			await assertWritableDirectory(paths.dataDir);
+			return `${paths.dataDir} 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`;
+		})
+	];
+}
+async function check(name, fallback, run, failureStatus = "fail") {
+	try {
+		return {
+			name,
+			status: "pass",
+			message: await run()
+		};
+	} catch (error) {
+		return {
+			name,
+			status: failureStatus,
+			message: error instanceof Error ? error.message : fallback
+		};
+	}
+}
+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.`;
+}
 //#endregion
 export { Doctor as default };