@zitadel/cli 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZITADEL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,345 @@
+# @zitadel/cli
+
+Scaffolds Zitadel auth (login, register, profile, middleware) into a Next.js app.
+
+```sh
+npx @zitadel/cli@latest setup --framework next --server <your-zitadel-server>
+```
+
+> **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.
+
+## Requirements
+
+- Node 20+
+- 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
+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.
+
+## Other commands
+
+- `zitadel doctor` — verify the generated files and local state
+- `zitadel status` — summarise the local project
+- `zitadel eject` — remove what setup wrote (alias: `zitadel uninstall`)
+
+## Reference
+
+<details>
+<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]`
+
+Display autocomplete installation instructions.
+
+```
+USAGE
+  $ zitadel autocomplete [SHELL] [-r]
+
+ARGUMENTS
+  [SHELL]  (zsh|bash|powershell) Shell type
+
+FLAGS
+  -r, --refresh-cache  Refresh cache (ignores displaying instructions)
+
+DESCRIPTION
+  Display autocomplete installation instructions.
+
+EXAMPLES
+  $ zitadel autocomplete
+
+  $ zitadel autocomplete bash
+
+  $ zitadel autocomplete zsh
+
+  $ zitadel autocomplete powershell
+
+  $ zitadel autocomplete --refresh-cache
+```
+
+_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v3.2.50/src/commands/autocomplete/index.ts)_
+
+## `zitadel commands`
+
+List all zitadel commands.
+
+```
+USAGE
+  $ zitadel commands [--json] [-c id|plugin|summary|type... | --tree] [--deprecated] [-x | ] [--hidden]
+    [--no-truncate | ] [--sort id|plugin|summary|type | ]
+
+FLAGS
+  -c, --columns=<option>...  Only show provided columns (comma-separated).
+                             <options: id|plugin|summary|type>
+  -x, --extended             Show extra columns.
+      --deprecated           Show deprecated commands.
+      --hidden               Show hidden commands.
+      --no-truncate          Do not truncate output.
+      --sort=<option>        [default: id] Property to sort by.
+                             <options: id|plugin|summary|type>
+      --tree                 Show tree of commands.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  List all zitadel commands.
+```
+
+_See code: [@oclif/plugin-commands](https://github.com/oclif/plugin-commands/blob/4.1.55/src/commands/commands.ts)_
+
+## `zitadel doctor`
+
+Verify generated files and local state.
+
+```
+USAGE
+  $ zitadel doctor [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [--fix]
+
+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.
+      --fix              Re-apply missing managed files.
+      --verbose          Verbose logging.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Verify generated files and local state.
+```
+
+## `zitadel eject`
+
+Remove managed files and local Zitadel state.
+
+```
+USAGE
+  $ zitadel eject [--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
+  Remove managed files and local Zitadel state.
+
+ALIASES
+  $ zitadel uninstall
+```
+
+## `zitadel help [COMMAND]`
+
+Display help for zitadel.
+
+```
+USAGE
+  $ zitadel help [COMMAND...] [-n]
+
+ARGUMENTS
+  [COMMAND...]  Command to show help for.
+
+FLAGS
+  -n, --nested-commands  Include all nested commands in the output.
+
+DESCRIPTION
+  Display help for zitadel.
+```
+
+_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/6.2.49/src/commands/help.ts)_
+
+## `zitadel search`
+
+Search for a command.
+
+```
+USAGE
+  $ zitadel search
+
+DESCRIPTION
+  Search for a command.
+
+  Once you select a command, hit enter and it will show the help for that command.
+```
+
+_See code: [@oclif/plugin-search](https://github.com/oclif/plugin-search/blob/v1.2.50/src/commands/search.ts)_
+
+## `zitadel setup`
+
+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]
+
+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.
+      --framework=<option>  Framework to target.
+                            <options: next>
+      --renderer=<option>   Renderer (default: react).
+                            <options: react|web-component>
+      --verbose             Verbose logging.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Create a Zitadel project and scaffold local auth.
+
+EXAMPLES
+  $ zitadel setup --framework next
+```
+
+## `zitadel status`
+
+Summarize the local project state.
+
+```
+USAGE
+  $ zitadel status [--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
+  Summarize the local project state.
+```
+
+## `zitadel uninstall`
+
+Remove managed files and local Zitadel state.
+
+```
+USAGE
+  $ zitadel uninstall [--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
+  Remove managed files and local Zitadel state.
+
+ALIASES
+  $ zitadel uninstall
+```
+
+## `zitadel version`
+
+```
+USAGE
+  $ zitadel version [--json] [--verbose]
+
+FLAGS
+  --verbose  Show additional information about the CLI.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+FLAG DESCRIPTIONS
+  --verbose  Show additional information about the CLI.
+
+    Additionally shows the architecture, node version, operating system, and versions of plugins that the CLI is using.
+```
+
+_See code: [@oclif/plugin-version](https://github.com/oclif/plugin-version/blob/2.2.46/src/commands/version.ts)_
+
+## `zitadel which`
+
+Show which plugin a command is in.
+
+```
+USAGE
+  $ zitadel which [--json]
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Show which plugin a command is in.
+
+EXAMPLES
+  See which plugin the `help` command is in:
+
+    $ zitadel which help
+
+  Use colon separators.
+
+    $ zitadel which foo:bar:baz
+
+  Use spaces as separators.
+
+    $ zitadel which foo bar baz
+
+  Wrap command in quotes to use spaces as separators.
+
+    $ zitadel which "foo bar baz"
+```
+
+_See code: [@oclif/plugin-which](https://github.com/oclif/plugin-which/blob/3.2.55/src/commands/which.ts)_
+<!-- commandsstop -->
+
+</details>
+
+## Links
+
+- Repository: [github.com/zitadel/nextgen](https://github.com/zitadel/nextgen)
+- Issues: [github.com/zitadel/nextgen/issues](https://github.com/zitadel/nextgen/issues)

package/SKILLS.md

@@ -0,0 +1,71 @@
+---
+name: zitadel-cli
+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.
+---
+
+# Zitadel CLI
+
+The `zitadel` CLI integrates Zitadel auth into an existing project and keeps the
+local config (`zitadel.json` and `.zitadel/**`) as the source of truth. Every
+command emits a JSON envelope, so you should drive it non-interactively and
+parse the result rather than scraping human output.
+
+## Invocation rules
+
+- Always pass `--non-interactive --json`. The envelope is the contract.
+- Add `--cwd <path>` when operating outside the current working directory.
+- Never run interactive prompts; `--non-interactive` (and `--json`) disable them.
+- See `README.md` (its commands section is generated from the CLI's own
+  metadata) or run `zitadel <command> --help` for the full per-command flag list.
+
+```sh
+npx @zitadel/cli@latest <command> --non-interactive --json
+```
+
+## Reading the envelope
+
+Each invocation prints one JSON object:
+
+- `status`: `ok` | `skipped` | `error`.
+- `cli_version`, `command`, `source`: always present.
+- On success: `data` with the command-specific payload.
+- On a no-op: `reason` (e.g. `no-framework-detected`, `orphaned-config`).
+- 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.
+
+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
+layer, not the envelope.
+
+## Commands
+
+- `setup` — create a Zitadel project and scaffold local auth (routes,
+  middleware, `.zitadel/**`, env templates). The project's default user schema
+  and login flow are provisioned server-side at creation, so setup neither
+  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.
+- `eject` (alias `uninstall`) — remove managed files and local Zitadel state;
+  requires `--force` when non-interactive.
+
+## 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
+```
+
+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/bin/run.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { execute } from "@oclif/core";
+
+await execute({ dir: import.meta.url });

package/dist/commands/apply.mjs

@@ -0,0 +1,62 @@
+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 { Flags } from "@oclif/core";
+import { consola as consola$1 } from "consola";
+import { createZitadelClient } from "@zitadel/api/client";
+//#region src/commands/apply.ts
+/**
+* `zitadel apply` — validate and upload repo config to the platform.
+*
+* Runs the sync loop to convergence, or (with `--dry-run`) previews the diff
+* without mutating. All validation — structural shape and `${VAR}` / `*_env`
+* reference presence — happens inside the sync engine ({@link buildSyncPlan}),
+* so an invalid or under-configured file fails with `E_VALIDATION` before any
+* platform call.
+*/
+var Apply = class Apply extends BaseCommand {
+	static description = "Validate and upload repo config to the platform.";
+	static hidden = true;
+	static flags = { environment: Flags.string({
+		char: "e",
+		description: "Target environment (default: development).",
+		options: [...environmentSchema.options]
+	}) };
+	async run() {
+		const { flags } = await this.parse(Apply);
+		await this.toMeta(flags);
+		const { cwd, source, env, dryRun, isTTY } = this.meta;
+		const secret = await readZitadelSecret(cwd);
+		consola$1.info(`Project   ${secret.project_id}`);
+		consola$1.info(`Server    ${source}`);
+		const syncers = makeSyncers({
+			client: createZitadelClient({
+				baseUrl: source,
+				token: secret.project_secret
+			}),
+			projectId: secret.project_id,
+			env
+		});
+		if (!dryRun) {
+			consola$1.start("Syncing schemas and flows to Zitadel");
+			await runSyncLoop(cwd, syncers);
+			consola$1.success("Sync complete");
+			return this.emit({
+				status: "ok",
+				data: { synced: true }
+			});
+		}
+		consola$1.start("Building plan (dry run)");
+		const plan = await buildSyncPlan(cwd, syncers, true);
+		const summary = summarizePlan(plan);
+		consola$1.success(`Plan: ${summary.creates} create${summary.creates === 1 ? "" : "s"}, ${summary.updates} update${summary.updates === 1 ? "" : "s"}, ${summary.deletes} delete${summary.deletes === 1 ? "" : "s"}`);
+		return this.emit({
+			status: "ok",
+			data: summary,
+			pretty: renderPlan(plan, isTTY)
+		});
+	}
+};
+//#endregion
+export { Apply as default };
+
+//# sourceMappingURL=apply.mjs.map

package/dist/commands/apply.mjs.map

@@ -0,0 +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"}