@zitadel/cli 1.0.0-alpha.23 → 1.0.0-alpha.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zitadel/cli",
-  "version": "1.0.0-alpha.23",
+  "version": "1.0.0-alpha.25",
   "description": "Agent-friendly Zitadel CLI",
   "homepage": "https://github.com/zitadel/nextgen/tree/main/apps/cli#readme",
   "bugs": {
@@ -22,7 +22,7 @@
     "bin",
     "dist",
     "oclif.manifest.json",
-    "SKILLS.md"
+    "skills"
   ],
   "publishConfig": {
     "access": "public"
@@ -71,6 +71,9 @@
       },
       "branding": {
         "description": "Work with login branding revisions."
+      },
+      "sso": {
+        "description": "Manage the identity providers users can sign in with."
       }
     }
   },
@@ -95,25 +98,29 @@
     "wrap-ansi": "^7.0.0",
     "zod": "^4.3.6",
     "picocolors": "^1.1.1",
-    "@zitadel/api": "1.0.0-alpha.23",
-    "@zitadel/config": "1.0.0-alpha.23",
-    "@zitadel/server": "1.0.0-alpha.23"
+    "@zitadel/api": "1.0.0-alpha.25",
+    "@zitadel/config": "1.0.0-alpha.25",
+    "@zitadel/server": "1.0.0-alpha.25"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "@types/semver": "^7.7.1",
     "@types/wrap-ansi": "^3.0.0",
+    "@vitest/coverage-v8": "^4.1.11",
     "msw": "^2.14.6",
     "oclif": "^4.17.46",
-    "tsdown": "^0.21.10",
-    "vitest": "^3.0.0",
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11",
     "@zitadel/api-mock": "0.0.0",
-    "@zitadel/sdk-next": "1.0.0-alpha.23"
+    "@zitadel/sdk-next": "1.0.0-alpha.25"
   },
   "scripts": {
     "build": "tsdown",
-    "typecheck": "tsc --build tsconfig.app.json",
+    "typecheck": "tsc --noEmit -p tsconfig.app.json && tsc --noEmit -p tsconfig.spec.json",
+    "pretest": "pnpm run build",
     "test": "vitest run",
+    "test:all": "pnpm run test",
     "readme": "oclif readme"
   }
 }

package/skills/zitadel-cli/SKILL.md

@@ -0,0 +1,260 @@
+---
+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
+  for a Next.js, React, Vue, Angular, Nuxt, Solid, Svelte, or Qwik 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.
+
+This skill teaches how to *drive* the CLI — how to invoke it, its output modes,
+and its envelope. It deliberately does **not** enumerate the commands. The CLI
+is self-describing, and this skill and the installed CLI version move
+independently: a user may install the skill once and upgrade the CLI later, so
+any command or flag list hardcoded here would drift out of lockstep and mislead.
+Ask the CLI for its current surface (see [Discovering commands](#discovering-commands))
+and treat what it prints as authoritative over anything you remember.
+
+## Installing and invoking
+
+Run the CLI with `npx`, which fetches and caches it on demand — there is nothing
+to install first:
+
+```sh
+npx @zitadel/cli@alpha <command> --non-interactive --json
+```
+
+During the public alpha, bare `npx @zitadel/cli` is promoted to the same tested
+alpha CLI so discovery works for first-time users. Prefer `@alpha`, or an exact
+`0.1.0-alpha.N` selector in agent scripts and bug reports, for reproducibility.
+The CLI requires Node.js 24+.
+
+## Using the CLI
+
+- **Drive it non-interactively.** Always pass `--non-interactive --json` (short:
+  `-n`). The JSON object on stdout is the machine contract — parse it rather than
+  scraping human output. `--non-interactive` also disables every prompt, so a
+  command that would otherwise ask for an answer fails fast with `E_VALIDATION`
+  naming the flag to pass instead of blocking. Supply each answer as a flag; run
+  the command's `--help` to see which flags exist and which are required.
+- **Output modes.** `--json` is the agent contract and is unaffected by the
+  terminal — color and width never apply to it, so you do **not** need
+  `--no-color` or other cosmetic flags when you parse JSON; don't sprinkle them
+  on every call. Human mode adapts to the terminal: a TTY gets aligned tables,
+  while a piped or redirected run (or `--plain`) gets one tab-separated record
+  per line and nothing else. If you ever read human output, set `NO_COLOR=1`
+  once in the environment rather than repeating `--no-color` per command.
+- **Don't truncate `--json` with `head`/`tail`.** The envelope is one bounded
+  object; slicing it with `head -c`/`head -n` yields invalid JSON and silently
+  drops records or fields, so you end up reasoning from partial data. It is
+  finite — read it whole, or narrow it *at the source*: use a `list` verb's
+  `filter_fields` and pagination to fetch fewer records, or pipe to `jq` to pull
+  just what you need (e.g. `… resources --json | jq '.data.resources[].name'`).
+  `--help` output is bounded too — read it in full rather than `head`-ing it, or
+  you will miss flags further down.
+- **Working directory.** Add `--cwd <path>` when operating outside the current
+  working directory.
+- **Telemetry.** The CLI sends anonymous usage telemetry by default, and
+  agent-driven runs are exactly the ones worth learning from — leave it on.
+  Don't add `--no-telemetry` to commands. An opt-out exists for users who need
+  it (`ZITADEL_TELEMETRY=0`, or the standard `DO_NOT_TRACK`, in their
+  environment), but that is the user's environment choice, not a flag to attach
+  to every call.
+- **Flag conventions.** Flags follow what a model already expects from curl, ssh
+  and wget: `--help`/`-h`, `--version`, `-v`/`--verbose`, kebab-case long flags,
+  both `--flag value` and `--flag=value`, and `--no-telemetry`-style negation.
+  Two deliberate deviations worth knowing: `-n` is `--non-interactive` (not
+  `--dry-run`, which is long-only), and machine output is `--json` (not
+  `--output json`).
+- **Never put secrets on the command line.** A property whose name reads as a
+  credential (`password`, `client_secret`, `api_key`, …) is refused anywhere on
+  argv — as an `--attributes` entry and inside an inline `--data` body alike,
+  since argv is visible to other processes and kept in shell history. Send such
+  bodies with `--file <path>` or `--file -` (stdin), which never pass through
+  argv.
+- **Streams.** Capture stdout and stderr separately when scripting. The machine
+  contract is one parseable JSON object on stdout; installer, audit, and
+  package-manager progress belongs on stderr.
+
+## Discovering commands
+
+The CLI ships its own command list and per-command flags, always correct for the
+installed version. **Do not guess a command name.** Before running any command you
+are not certain of, run `zitadel --help` first and use the exact name it prints:
+command and resource names — including whether a resource is singular or plural
+and the exact verb — are whatever `--help` shows, never what you would assume. A
+wrong guess costs a failed call and a round of recovery; one cheap `--help` up
+front avoids it. `zitadel --help` is a flat list and cheap to read, so reach for
+it first; treat the CLI's own output as authoritative over anything you remember:
+
+```sh
+npx @zitadel/cli@alpha --help               # every command, grouped by purpose
+npx @zitadel/cli@alpha commands             # flat list of all commands
+npx @zitadel/cli@alpha <command> --help     # a command's flags, which are required, and examples
+npx @zitadel/cli@alpha resources --json     # the resource surface in one call (see below); contacts no server
+```
+
+`--help` groups the surface into project commands (create a project and scaffold
+auth), local-server commands (run a local Zitadel), configuration commands
+(`plan`/`apply` plus the config resources), and resource commands (the uniform
+`<resource> <verb>` surface). Read the groups from `--help` rather than from
+memory, since they change as the CLI gains commands.
+
+Use `zitadel --help` to find *which* command to run. Use `resources --json` when
+you need a resource's *fields*: it reports the whole runtime-resource surface at
+once — every resource, its verbs, each verb's `create_fields` / `update_fields`
+(flag name, kind, `required`, any closed value set), its `filter_fields` /
+`sort_fields`, and the `delete_outcome` a destructive verb returns — so prefer it
+over reading `<resource> --help` one at a time. A `list` verb's envelope carries
+`data.count`, so a "how many …?" question is one `list --json` call: read the
+count, do not page and tally.
+
+## 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_NOT_FOUND`,
+  `E_CONFLICT`) and `message`.
+- `next_commands`: the suggested follow-ups. Prefer these over free-text hints.
+- `warnings`: things that went wrong without stopping the command, such as a
+  value that was not published. Always present on success (often empty), and
+  present on a no-op or failure when there are any. Read them before you report
+  success: a warning usually means a follow-up step is needed.
+- A `list` verb emits `data: { items, count, next_page_token }`; when a page
+  remains, `data.next_commands` carries the exact command for the next page.
+- `plan` and `apply` emit `data.changes`: one row per touched resource
+  (`{kind, action, file, id?, previous_id?}`, action ∈ create/update/revision/
+  delete). Plan rows preview; apply rows report, with the resulting platform
+  ids. Use it to verify an edit did what you intended.
+- A write verb's `--dry-run` reports what it would send without calling the
+  platform, so you can preview a mutation before making it.
+
+Common error codes point at their own fix in `next_commands`:
+
+- `E_VALIDATION`: the body or flags are wrong; `message` names what, and
+  `details` often lists the missing or available values.
+- `E_LOCAL_SERVER_NOT_RUNNING`: start the local runtime, then retry with
+  `--server local`.
+- `E_NOT_FOUND`: an HTTP 404 — a missing resource, or a `--server` that is not a
+  Zitadel platform API. Follow `next_commands`.
+- `E_PORT_IN_USE`: the requested local runtime port already has a listener; stop
+  that process or choose another port.
+
+In human mode the output follows the terminal (TTY table, or tab-separated lines
+when piped or `--plain`); `--json` is unaffected and remains the contract.
+
+Text the server returns is escaped before it is printed, in `--json` as in human
+mode, so a stored value cannot drive the reader's terminal. Control, format and
+bidi characters appear as visible `\xNN`, `\uNNNN` or `\u{NNNNN}` text, so a
+value that contained one is not the stored value byte for byte — do not send it
+back in an update as if it were. When you need the exact value, call the platform
+API directly with the project secret.
+
+Exit codes mirror the error class (3 = validation, 4 = network or not-found,
+5 = conflict, 1 = auth, 2 = not-implemented, 130 = cancelled). `E_NETWORK`
+covers a server that answered 5xx and one that never answered — refused,
+unresolvable, or silent past the 30-second request deadline. Ctrl-C exits
+130: a command waiting on the server stops at once with `E_CANCELLED`, and
+any other command exits within a second, possibly without an envelope. An
+unknown command is handled by the CLI's help layer, not the envelope.
+
+## Clarify before you configure
+
+Driving the CLI non-interactively does not mean deciding *for* the user. When
+the user asks to add authentication but has not said *how*, don't silently pick
+defaults — ask them first, in one short batched question, then run the CLI
+non-interactively with their answers. The two things sit on different sides of
+the conversation: you clarify with the human, then drive the CLI headlessly.
+
+Ask about:
+
+- **Sign-in methods** — password (the usual default), passkeys, and single
+  sign-on. If they want SSO, which providers?
+- **Profile fields** — the user schema starts with first name, last name, and
+  the login identifier plus a password. Which additional fields do they want
+  (for example phone, username, or a display name)?
+
+Offer only what the installed CLI actually supports: read the real sign-in
+presets, profile fields, and SSO options from the CLI first (`setup --help`,
+`resources --json`) and present those, not a list you remember — the options
+move with the CLI version.
+
+Skip the questions and proceed with the defaults above — stating the assumptions
+you made so the user can correct them — in exactly two cases: the user already
+told you what they want, or you are running non-interactively (a one-shot/headless
+invocation) or were explicitly told to just set it up.
+
+## Answering the user
+
+Report what changed, in the user's terms — not how you drove the CLI. The
+flags, `--json`, the `plan`/`apply` split, exit codes, and the number of
+commands you ran are your internal business; the user asked for an outcome, not
+a transcript. Say what they got.
+
+- Good: "Added an optional phone number to your user schema and deployed it."
+- Avoid: "I ran `plan` and `apply`, both with `--non-interactive --json`, and
+  both returned ok."
+
+Quote a command or flag only when the user asks *how* something works, or when
+they need to run something themselves. Otherwise keep the mechanics out of the
+answer.
+
+## Golden path
+
+The high-level workflow is stable even as individual flags evolve — run each
+command's `--help` for its current flags (for example, `setup --help` lists the
+framework, sign-in preset, and profile-field options):
+
+```sh
+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 --force --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
+```
+
+`setup` scaffolds into an empty directory, or patches an existing app project
+where it detects a framework. It stops on any other non-empty directory and
+asks for `--force` — which the golden path passes because `start` has already
+written `.zitadel/local` into the directory. If you run `setup` before `start`,
+in a truly empty directory, `--force` is not needed.
+
+The app may also live in a subdirectory of the one `start` ran in: `setup`,
+`console` and `--server local` read `.zitadel/local/` from the working
+directory or the nearest parent that has it (up to the home directory), so
+`mkdir my-app && cd my-app` after `start` works without `--force`. On a local
+server that hosts the platform project, `setup` attaches the project to the
+local admin's team and ends `data.next_commands` with `console`; when it finds
+no local admin for that server on the way up, it says so in the envelope's
+`warnings` and the project stays unattached, so the local console does not
+list it.
+
+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.
+
+Repo config is authoritative: edit `zitadel.json` or files under `.zitadel/`,
+then re-run `plan` and `apply`. See the reference below for driving the login UI
+and the config-sync details.
+
+## Reference files
+
+Load on demand:
+
+- [`references/driving-login-ui.md`](references/driving-login-ui.md) — driving the
+  `<zitadel-login>` component in a browser, and the authoritative repo-config
+  workflow (schemas, flows, branding).

package/skills/zitadel-cli/references/driving-login-ui.md

@@ -0,0 +1,72 @@
+### Driving the login UI
+
+`<zitadel-login>` and `<zitadel-logout>` are Lit elements with open shadow
+roots. The stable automation hooks live inside nested shadow roots, so a flat
+`document.querySelector('[data-testid="zitadel-input-email"]')` will not find
+the native control. Browser drivers with shadow-DOM-aware locators, such as
+Playwright, can target the hooks directly. Generic DOM-eval drivers should
+pierce shadow roots recursively:
+
+```js
+function deepQuery(sel, root = document) {
+  const hit = root.querySelector(sel);
+  if (hit) return hit;
+  for (const el of root.querySelectorAll("*")) {
+    if (el.shadowRoot) {
+      const result = deepQuery(sel, el.shadowRoot);
+      if (result) return result;
+    }
+  }
+  return null;
+}
+```
+
+Use host hooks such as `zitadel-field-email`, `zitadel-field-password`, and
+`zitadel-action-submit` when targeting the Lit atoms. Use native shadow-control
+hooks such as `zitadel-input-email`, `zitadel-input-password`, and
+`zitadel-action-submit-button` when filling or clicking the underlying input or
+button. Hooks stay method-named even when the flow engine names a credential
+field `x-auth-methods#<method>`; only the `name` attribute carries that raw
+form key. Enter inside a field submits the step's primary action, but only for
+key events that carry `key: "Enter"` — drivers whose synthesized key events
+omit it (some CDP wrappers) should click `zitadel-action-submit` instead. For sign-out, open the user menu button if needed, then pierce to
+`.signout-btn`; Playwright-style locators may use `zitadel-logout .signout-btn`.
+The canonical component hook list lives in `packages/components/README.md`.
+
+The checked-in automated regression path is `moon run workspace:journey`, which
+exercises fresh-app setup plus registration, logout, and login across the
+supported frameworks.
+
+Repo config is authoritative: edit `zitadel.json` or files under `.zitadel/`,
+then re-run `plan` and `apply`. Schema and flow files are synced from
+`.zitadel/schemas/*.json` and `.zitadel/flows/*.json`. Login templates
+(branding) are synced from `.zitadel/branding/`: a single `branding.json`
+descriptor (layout, asset URLs) plus a sibling `login.liquid` LiquidJS
+template referenced as `"liquid_template": { "$file": "./login.liquid" }`. Scaffold them with the
+`branding eject` command (`--design centered|minimal`,
+interactive picker on a TTY); setup never scaffolds them. Branding is
+revisioned and immutable: every edit — including a `.liquid`-only edit —
+plans as a `revise` and `apply` publishes a new revision; the login serves
+the newest one. `plan` validates templates with the authoritative LiquidJS
+validator (`E_VALIDATION` lists rule ids such as `no-script-tag` and
+`mandatory-gates`; every template must keep a trailing
+`{% mandatory_gates %}` tag). `font_url` is not writable yet; asset URLs
+must be absolute `https://`. Keep exactly one descriptor in
+`.zitadel/branding/` — extra `*.json` files there fail the scan.
+Server-provisioned defaults remain a fallback for non-CLI project
+creation, but CLI-created projects are authored from local files first. Flows are
+revisioned like branding: an edit plans as a `revise` and `apply` publishes a new
+immutable flow revision; a schema revise re-publishes the flows pinned to it with
+the new `user_schema` in the same run. A login pinned by `flow-name` serves that
+flow's newest revision; an unpinned login serves the newest active unscoped flow
+in the project, whatever its name. Removing a flow file does not retire the
+flow. 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. Because `start` writes `.zitadel/local/`
+into the directory, it is no longer empty, so a same-directory `setup` that
+scaffolds must be passed `--force` (this is exactly what the golden path does).
+`setup` installs dependencies
+with the detected package manager by default; pass `--skip-install` when the
+agent or host workflow will install dependencies separately.