@zitadel/cli 0.1.0-alpha.9 → 1.0.0-alpha.20

package/README.md

@@ -1,6 +1,6 @@
 # @zitadel/cli
 
-Scaffolds Zitadel auth (login, register, profile, middleware) into a Next.js, React, Vue, Angular, or Nuxt app.
+Scaffolds Zitadel auth (login, register, profile, middleware/proxy) into a Next.js, Nuxt, React, Vue, Angular, Solid, Svelte, or Qwik app.
 
 ```sh
 npx @zitadel/cli@alpha start
@@ -15,9 +15,10 @@ automation when reproducibility matters.
 
 ## Requirements
 
-- Node 24+
+- Node from the supported range in `package.json#engines` (currently ≥ 24)
 - Docker only when using the optional Docker runtime backend
-- A Next.js project, or an empty directory where setup can scaffold one
+- An app in one of the eight supported frameworks, or an empty directory
+  where setup can scaffold one
 
 ## Quickstart
 
@@ -31,20 +32,29 @@ npm run dev
 ```
 
 `start` runs the `@zitadel/server` npm binary by default and stores runtime data
-under `.zitadel/local/`. Remote-server setup can use `--server <url>` without
-starting a local runtime. Use `--runtime docker`, `--image`, or
-`ZITADEL_LOCAL_IMAGE` for advanced Docker backend debugging.
+under `.zitadel/local/` (SQLite by default). Remote-server setup can use
+`--server <url>` without starting a local runtime. Use `--runtime docker`,
+`--image`, or `ZITADEL_LOCAL_IMAGE` for advanced Docker backend debugging.
 `setup --server local` creates a project on that local server, asks which
-framework to scaffold when the directory is fresh, writes the Next.js app into
-the current directory, scaffolds `app/login`, `app/register`, `app/profile`, and
-`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
+framework to scaffold when the directory is fresh (and which login design to
+use), writes the app into the current directory, and scaffolds the framework's
+idiomatic auth routes plus the proxy layer — for Next.js that means
+`app/login`, `app/register`, `app/profile`, and `proxy.ts` for Next 16+ or
+`middleware.ts` for older versions; other frameworks get their equivalents
+from the same patcher system. In a pre-existing app, setup derives the
+embedding posture from the app instead of assuming a fresh skeleton: the
+scaffolded pages take the `variant="widget"` posture inside your app's own
+shell, recorded in the scaffold manifest and verified by `doctor`. Fresh
+scaffolds also replace the starter home page with a redirect to `/login`.
+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.
+from versioned local defaults; setup writes editable copies into
+`.zitadel/schemas/default-human-user.json` and
+`.zitadel/flows/default-login.json`, uploads them through the schema and flow
+APIs, then seeds `.zitadel/state.json` so `zitadel plan` is immediately empty.
+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:
@@ -60,15 +70,40 @@ registration/login, and optional passkey setup after password registration.
 Users who skip passkey setup can still sign in with password; users who add a
 passkey can sign in with either credential.
 
+Repo config is authoritative: edit `zitadel.json`, `.zitadel/schemas/*.json`,
+`.zitadel/flows/*.json`, or `.zitadel/branding/` (a `branding.json` descriptor
+plus a `login.liquid` LiquidJS template), then re-run `zitadel plan` and
+`zitadel apply`. Server-provisioned defaults remain a fallback for non-CLI
+project creation, but CLI-created projects are authored from local files first.
+Login templates are supported: scaffold them with the `branding eject` command
+(`--design centered|split|split-right|hero|minimal`) or `setup --design <name>`;
+every edit publishes a new immutable branding revision and the login serves
+the newest one. Flow create, read, list, update, and delete are available; the
+server enforces flow lifecycle rules such as draft-only edits.
+
+For agent scripts, pass `--non-interactive --json` and capture stdout and stderr
+separately. The CLI contract is one parseable JSON object on stdout; terminals
+and agent UIs may display stderr package-manager progress together with stdout.
+
 ## Other commands
 
+- `zitadel claim` — attach the project to your team (opens the claim page,
+  polls for completion; team attachment then shows in `setup`, `status`, and
+  `doctor`)
 - `zitadel doctor` — verify the local runtime and generated project files
+  (including scaffold drift and dependency-version alignment)
 - `zitadel status` — summarise the local runtime and project
 - `zitadel plan` — validate config and preview sync changes without mutation
 - `zitadel apply` — validate and upload repo config to Zitadel
+- `zitadel branding eject` — scaffold an editable login template from a design
+- `zitadel schemas list` — list the project's user schemas
 - `zitadel eject` — remove what setup wrote (alias: `zitadel uninstall`)
 - `zitadel start|stop|logs|reset` — manage the local runtime
 
+The full agent-facing contract (JSON envelope, posture rules, claim flow,
+doctor repair) is [`SKILLS.md`](https://github.com/zitadel/nextgen/blob/main/apps/cli/SKILLS.md),
+which ships in this package.
+
 ## Reference
 
 <details>
@@ -77,6 +112,8 @@ passkey can sign in with either credential.
 <!-- commands -->
 * [`zitadel apply`](#zitadel-apply)
 * [`zitadel autocomplete [SHELL]`](#zitadel-autocomplete-shell)
+* [`zitadel branding eject`](#zitadel-branding-eject)
+* [`zitadel claim`](#zitadel-claim)
 * [`zitadel commands`](#zitadel-commands)
 * [`zitadel doctor`](#zitadel-doctor)
 * [`zitadel eject`](#zitadel-eject)
@@ -84,6 +121,7 @@ passkey can sign in with either credential.
 * [`zitadel logs`](#zitadel-logs)
 * [`zitadel plan`](#zitadel-plan)
 * [`zitadel reset`](#zitadel-reset)
+* [`zitadel schemas list`](#zitadel-schemas-list)
 * [`zitadel search`](#zitadel-search)
 * [`zitadel setup`](#zitadel-setup)
 * [`zitadel start`](#zitadel-start)
@@ -99,8 +137,8 @@ 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]
+    [--telemetry] [-e development|preview|production]
 
 FLAGS
   -c, --cwd=<value>           Project directory to operate on.
@@ -111,6 +149,7 @@ FLAGS
   -s, --server=<value>        Override the resolved server URL.
       --debug                 Debug logging.
       --dry-run               Preview without mutating files or the platform.
+      --[no-]telemetry        Send anonymous usage analytics. Disable with --no-telemetry.
       --verbose               Verbose logging.
 
 GLOBAL FLAGS
@@ -151,6 +190,69 @@ EXAMPLES
 
 _See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v3.2.50/src/commands/autocomplete/index.ts)_
 
+## `zitadel branding eject`
+
+Take ownership of the login template: scaffold .zitadel/branding/ from a shipped design.
+
+```
+USAGE
+  $ zitadel branding eject [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry] [--design centered|split|split-right|hero|minimal]
+
+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.
+      --design=<option>  Design to start from (default: centered).
+                         <options: centered|split|split-right|hero|minimal>
+      --dry-run          Preview without mutating files or the platform.
+      --[no-]telemetry   Send anonymous usage analytics. Disable with --no-telemetry.
+      --verbose          Verbose logging.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Take ownership of the login template: scaffold .zitadel/branding/ from a shipped design.
+```
+
+## `zitadel claim`
+
+Attach this project to a team so it becomes permanent. Opens a browser to finish signing in.
+
+```
+USAGE
+  $ zitadel claim [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry] [--no-open] [--timeout <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.
+      --no-open          Print the link instead of opening a browser.
+      --[no-]telemetry   Send anonymous usage analytics. Disable with --no-telemetry.
+      --timeout=<value>  Seconds to wait for the browser step. Defaults to the link's own expiry (10 minutes).
+      --verbose          Verbose logging.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Attach this project to a team so it becomes permanent. Opens a browser to finish signing in.
+
+EXAMPLES
+  $ zitadel claim
+
+  $ zitadel claim --no-open
+
+  $ zitadel claim --timeout 120
+```
+
 ## `zitadel commands`
 
 List all zitadel commands.
@@ -186,22 +288,23 @@ 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>] [--runtime binary|docker]
+  $ zitadel doctor [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry] [--fix] [--image <value>] [--port <value>] [--runtime binary|docker]
 
 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.
-      --image=<value>    Container image to check.
-      --port=<value>     [default: 8080] Local HTTP port.
-      --runtime=<option> Local runtime backend.
-                         <options: binary|docker>
-      --verbose          Verbose logging.
+  -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               Repair missing files and stale managed wiring.
+      --image=<value>     Container image to check.
+      --port=<value>      [default: 8080] Local HTTP port.
+      --runtime=<option>  Local runtime backend.
+                          <options: binary|docker>
+      --[no-]telemetry    Send anonymous usage analytics. Disable with --no-telemetry.
+      --verbose           Verbose logging.
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -217,6 +320,7 @@ Remove managed files and local Zitadel state.
 ```
 USAGE
   $ zitadel eject [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -225,6 +329,7 @@ FLAGS
   -s, --server=<value>   Override the resolved server URL.
       --debug            Debug logging.
       --dry-run          Preview without mutating files or the platform.
+      --[no-]telemetry   Send anonymous usage analytics. Disable with --no-telemetry.
       --verbose          Verbose logging.
 
 GLOBAL FLAGS
@@ -263,8 +368,8 @@ Show local Zitadel server logs.
 
 ```
 USAGE
-  $ zitadel logs [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [--follow]
-    [--tail <value>]
+  $ zitadel logs [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry] [--follow] [--tail <value>]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -275,6 +380,7 @@ FLAGS
       --dry-run          Preview without mutating files or the platform.
       --follow           Follow logs.
       --tail=<value>     [default: 200] Number of lines to show.
+      --[no-]telemetry   Send anonymous usage analytics. Disable with --no-telemetry.
       --verbose          Verbose logging.
 
 GLOBAL FLAGS
@@ -290,8 +396,8 @@ 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]
+    [--telemetry] [-e development|preview|production]
 
 FLAGS
   -c, --cwd=<value>           Project directory to operate on.
@@ -302,6 +408,7 @@ FLAGS
   -s, --server=<value>        Override the resolved server URL.
       --debug                 Debug logging.
       --dry-run               Preview without mutating files or the platform.
+      --[no-]telemetry        Send anonymous usage analytics. Disable with --no-telemetry.
       --verbose               Verbose logging.
 
 GLOBAL FLAGS
@@ -318,6 +425,7 @@ Delete the local Zitadel server runtime and data.
 ```
 USAGE
   $ zitadel reset [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -326,6 +434,7 @@ FLAGS
   -s, --server=<value>   Override the resolved server URL.
       --debug            Debug logging.
       --dry-run          Preview without mutating files or the platform.
+      --[no-]telemetry   Send anonymous usage analytics. Disable with --no-telemetry.
       --verbose          Verbose logging.
 
 GLOBAL FLAGS
@@ -335,6 +444,35 @@ DESCRIPTION
   Delete the local Zitadel server runtime and data.
 ```
 
+## `zitadel schemas list`
+
+List revisions of a user-schema by objectType.
+
+```
+USAGE
+  $ zitadel schemas list -t <value> [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry] [-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.
+  -t, --object-type=<value>   (required) Filter revisions by objectType (e.g. human-user).
+      --debug                 Debug logging.
+      --dry-run               Preview without mutating files or the platform.
+      --[no-]telemetry        Send anonymous usage analytics. Disable with --no-telemetry.
+      --verbose               Verbose logging.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  List revisions of a user-schema by objectType.
+```
+
 ## `zitadel search`
 
 Search for a command.
@@ -358,23 +496,65 @@ Create a Zitadel project and scaffold local auth.
 ```
 USAGE
   $ zitadel setup [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
-    [--framework next|nuxt|react|vue|angular] [--renderer react|web-component] [--dev-port <value>] [--skip-install]
+    [--telemetry] [--framework next|nuxt|react|vue|solid|svelte|qwik|angular] [--renderer react] [--dev-port <value>]
+    [--skip-install] [--preset password-first|passkey-first] [--use-case minimal|consumer|business] [--design
+    centered|split|split-right|hero|minimal]
 
 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.
-      --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|nuxt|react|vue|angular>
-      --renderer=<option>   Renderer (default: react).
-                            <options: react|web-component>
-      --skip-install        Do not install dependencies after setup updates package.json.
-      --verbose             Verbose logging.
+  -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.
+
+  --design=<option>
+      Login design to eject into .zitadel/branding/ and publish as branding revision 1. Skips the wizard's design
+      question. When omitted in non-interactive runs, the login uses the built-in template; run the `branding eject`
+      command later to customize. Split-family designs (split, split-right, hero) collapse their brand pane by container
+      width: narrow containers — including widget-posture embeds at card width — render the compact brand mark instead
+      (logo_url, else hero_url, from .zitadel/branding/branding.json; hero falls back to editable text).
+      <options: centered|split|split-right|hero|minimal>
+
+  --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|nuxt|react|vue|solid|svelte|qwik|angular>
+
+  --preset=<option>
+      Sign-in preset for the scaffolded schema and login flow (default: password-first).
+      <options: password-first|passkey-first>
+
+  --renderer=<option>
+      Renderer (default: react). Not yet available: web-component.
+      <options: react>
+
+  --skip-install
+      Do not install dependencies after setup updates package.json.
+
+  --[no-]telemetry
+      Send anonymous usage analytics. Disable with --no-telemetry.
+
+  --use-case=<option>
+      Use case for the scaffolded schema fields: who signs in to the app (default: minimal).
+      <options: minimal|consumer|business>
+
+  --verbose
+      Verbose logging.
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -394,21 +574,22 @@ Start a local Zitadel server.
 
 ```
 USAGE
-  $ zitadel start [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [--image
-    <value>] [--port <value>] [--runtime binary|docker]
+  $ zitadel start [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry] [--image <value>] [--port <value>] [--runtime binary|docker]
 
 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.
-      --runtime=<option> Local runtime backend.
-                         <options: binary|docker>
-      --verbose          Verbose logging.
+  -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.
+      --runtime=<option>  Local runtime backend.
+                          <options: binary|docker>
+      --[no-]telemetry    Send anonymous usage analytics. Disable with --no-telemetry.
+      --verbose           Verbose logging.
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -424,6 +605,7 @@ Summarize the local Zitadel server and project state.
 ```
 USAGE
   $ zitadel status [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -432,6 +614,7 @@ FLAGS
   -s, --server=<value>   Override the resolved server URL.
       --debug            Debug logging.
       --dry-run          Preview without mutating files or the platform.
+      --[no-]telemetry   Send anonymous usage analytics. Disable with --no-telemetry.
       --verbose          Verbose logging.
 
 GLOBAL FLAGS
@@ -448,14 +631,17 @@ Stop the local Zitadel server.
 ```
 USAGE
   $ zitadel stop [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry] [--all]
 
 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.
+      --all              Stop all discovered CLI-managed local Zitadel runtime processes.
       --debug            Debug logging.
       --dry-run          Preview without mutating files or the platform.
+      --[no-]telemetry   Send anonymous usage analytics. Disable with --no-telemetry.
       --verbose          Verbose logging.
 
 GLOBAL FLAGS
@@ -472,6 +658,7 @@ Remove managed files and local Zitadel state.
 ```
 USAGE
   $ zitadel uninstall [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
+    [--telemetry]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -480,6 +667,7 @@ FLAGS
   -s, --server=<value>   Override the resolved server URL.
       --debug            Debug logging.
       --dry-run          Preview without mutating files or the platform.
+      --[no-]telemetry   Send anonymous usage analytics. Disable with --no-telemetry.
       --verbose          Verbose logging.
 
 GLOBAL FLAGS