@zitadel/cli 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zitadel/cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Agent-friendly Zitadel CLI",
   "homepage": "https://github.com/zitadel/nextgen/tree/main/apps/cli#readme",
   "bugs": {
@@ -49,31 +49,31 @@
     ],
     "topics": {
       "users": {
-        "description": "Manage the users of the project."
+        "description": "Create and manage users."
       },
       "teams": {
-        "description": "Manage the teams of the project."
+        "description": "Create and manage teams."
       },
       "sessions": {
-        "description": "Inspect and revoke the sessions of the project."
+        "description": "View and revoke sessions."
       },
       "events": {
-        "description": "Read the audit event stream of the project."
+        "description": "View events."
       },
       "grants": {
-        "description": "Manage collaboration grants on the project."
+        "description": "Manage access grants."
       },
       "projects": {
-        "description": "Inspect and update the projects visible to this credential."
+        "description": "View and update projects."
       },
       "schemas": {
-        "description": "Inspect user-schema revisions."
+        "description": "View user schemas."
       },
       "branding": {
-        "description": "Work with login branding revisions."
+        "description": "Manage the login branding."
       },
       "auth-method": {
-        "description": "Turn sign-in methods on or off for a user schema."
+        "description": "Configure how users sign in."
       },
       "auth-method:password": {
         "description": "Turn password sign-in on or off."
@@ -83,6 +83,36 @@
       },
       "auth-method:sso": {
         "description": "Add or remove identity providers."
+      },
+      "origin": {
+        "description": "Manage the project's allowed origins."
+      },
+      "release": {
+        "description": "Build and manage releases."
+      },
+      "deployment": {
+        "description": "Deploy releases and roll them back."
+      },
+      "preview": {
+        "description": "Deploy and manage pull-request preview URLs."
+      },
+      "variable": {
+        "description": "Manage project variables."
+      },
+      "idps": {
+        "description": "Manage identity provider connections."
+      },
+      "flow-definitions": {
+        "description": "View login flows."
+      },
+      "policies": {
+        "description": "View and test policies."
+      },
+      "env": {
+        "description": "Show and bind environments."
+      },
+      "api": {
+        "description": "Call any operation of the Zitadel API."
       }
     }
   },
@@ -97,20 +127,20 @@
     "@oclif/plugin-search": "^1.2.50",
     "@oclif/plugin-version": "^2.2.46",
     "@oclif/plugin-which": "^3.2.55",
-    "@zitadel/api": "0.1.0",
-    "@zitadel/config": "0.1.0",
-    "@zitadel/server": "0.1.0",
+    "@zitadel/api": "0.3.0",
+    "@zitadel/config": "0.3.0",
+    "@zitadel/server": "0.3.0",
     "ajv": "^8.20.0",
     "consola": "^3.4.2",
     "magicast": "^0.5.3",
     "mixpanel": "^0.18.1",
+    "picocolors": "^1.1.1",
+    "rosie-skills": "^0.8.5",
     "safe-stable-stringify": "^2.5.0",
     "semver": "^7.7.3",
     "undici": "^7.29.1",
     "wrap-ansi": "^7.0.0",
-    "zod": "^4.3.6",
-    "picocolors": "^1.1.1",
-    "rosie-skills": "^0.8.5"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^24.19.1",
@@ -118,13 +148,15 @@
     "@types/wrap-ansi": "^3.0.0",
     "@vitest/coverage-v8": "^4.1.11",
     "@zitadel/api-mock": "0.0.0",
-    "@zitadel/sdk-next": "0.1.0",
+    "@zitadel/sdk-next": "0.3.0",
+    "@zitadel/vitest-config": "0.0.0",
     "msw": "^2.14.6",
     "oclif": "^4.17.46",
     "tsdown": "^0.23.0",
     "typescript": "^6.0.3",
     "vite": "^8.3.1",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "yaml": "^2.9.0"
   },
   "scripts": {
     "build": "tsdown",

package/skills/zitadel-cli/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   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, Nuxt, SvelteKit, SolidStart, Qwik Router, TanStack Start, React,
-  Vue, Angular, Solid, Svelte, or Qwik app, or plan and apply Zitadel config
+  Vue, Angular, Solid, Svelte, or Qwik app, or build and deploy Zitadel config
   changes from repo state.
 ---
 
@@ -67,11 +67,47 @@ upgrade, so upgrade the app and rerun rather than retrying.
   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'`).
+  just what you need (e.g. `… resources --json | jq '.data.items[].topic'`).
   `--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.
+  working directory. A relative `--env-file` path is still read from the
+  current directory, not from `--cwd` (`--cwd app --env-file app/.env.ci`):
+  Node reads `--env-file` itself before the CLI starts and exits 9 with
+  `node: <path>: not found`, and no envelope, when the file is not there.
+- **Server and project.** A command that talks to a project reads
+  `ZITADEL_URL`, `ZITADEL_PROJECT_ID` and `ZITADEL_PROJECT_SECRET`, each from the
+  first source that has it: `--server` (the URL only), `--env-file <path>`, the
+  process environment, `.env.<env>.local`, `.env.local`, `.env.<env>`, `.env`,
+  then `.zitadel/secret`. Only the default `development` environment reads
+  `.env.local` and `.zitadel/secret` (setup's project); `--env-file` reads that
+  file and the process environment only.
+  `<env>` is `--env`, else `ZITADEL_ENV`, else a hosting platform's own signal
+  (`VERCEL_ENV`, or Netlify's `CONTEXT` inside a Netlify build), else
+  `development`. A missing value fails with `E_VALIDATION` naming the variable
+  and the files it looked in; there is no cloud default outside `setup`, and
+  the server is never read from `zitadel.json`. `zitadel env` shows what resolved and where
+  each value came from; `zitadel env add <name>` binds another environment to a
+  project. The project it creates has never had a release, so the environment
+  serves the server's own defaults until something is deployed to it: run the
+  `deploy` the result's `next_commands` names, against the file it wrote
+  (`--env-file .env.<name>.local`). A person at a terminal is asked whether to
+  deploy there and then; your runs never are, so they never deploy — run that
+  `deploy` yourself. `data.deployment` carries the `release_id`,
+  `content_hash`, `deployment_id` and `origins` when a person accepted, and is
+  null otherwise — a failed deploy is a warning, never a failed `env add`.
+- **Origins.** `zitadel origin add <url> --kind primary|preview`, `origin list`
+  and `origin rm <url>` manage the URLs a project serves: a `primary` origin is
+  where the app is served, a `preview` pattern (it may hold a `*`) is where
+  pull-request builds run. They need the project secret, not the preview token.
+  An empty list admits every origin, so removing the last one opens the project
+  up; `origin rm` asks first and needs `--force` when non-interactive. Removing
+  a preview pattern leaves its live previews served until they expire.
+  `deploy` lands only on primary origins and fails with `E_VALIDATION` without
+  one; its `next_commands` name the step that gives the project one. `setup`
+  0.1.0 registered the app's URL (`ZITADEL_ISSUER`) as a `preview` origin,
+  which `origin add --kind primary` refuses with `E_CONFLICT`: `doctor` warns
+  (`issuer-origin`) and `doctor --fix` makes it primary.
 - **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
@@ -122,36 +158,40 @@ upgrade, so upgrade the app and rerun rather than retrying.
   `${{ NAME }}` reference to a project variable is not a secret and may stay on
   argv (a connection's `client_secret` takes nothing else); write it in single
   quotes, since inside double quotes the shell reads `${` as its own expansion.
-- **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.
+- **Streams.** Capture stdout and stderr separately when scripting, into files
+  outside the app directory: `setup` scaffolds a new app only into an empty
+  directory. 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:
+are not certain of, look it up first and use the exact name the CLI 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:
+and the exact verb — are whatever the CLI shows, never what you would assume. A
+wrong guess costs a failed call and a round of recovery; one cheap lookup up
+front avoids it. `zitadel --help` lists each family of commands (`users`,
+`release`) as one row, so it stays short; `zitadel commands` is the flat list of
+every command, verbs included, and `zitadel <family> --help` lists one family's
+verbs. Treat the CLI's own output as authoritative over anything you remember:
 
 ```sh
-npx @zitadel/cli@latest --help               # every command, grouped by purpose
+npx @zitadel/cli@latest --help               # every command family, grouped by purpose
 npx @zitadel/cli@latest commands             # flat list of all commands
 npx @zitadel/cli@latest <command> --help     # a command's flags, which are required, and examples
 npx @zitadel/cli@latest resources --json     # the resource surface in one call (see below); contacts no server
 npx @zitadel/cli@latest api ls --json        # every API operation, its parameters, body and paging; 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.
+`--help` groups the commands by what you are doing: getting started, local
+development, users and teams, authentication, configuration and releases, and
+diagnostics and utilities. A family such as `users` is one row, and
+`zitadel users --help` lists its verbs. 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
+Use `zitadel --help` to find *which* family or command to run, and
+`zitadel commands` for the exact verb. 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` /
@@ -161,6 +201,11 @@ over reading `<resource> --help` one at a time. A `list` verb's envelope carries
 you pass `--all`, so a "how many …?" question is one `list --all --json` call:
 read the count, do not page and tally.
 
+To find the users still on an older revision of a schema, filter on the
+schema's object type and exclude the newest revision's URL:
+`users list --filter schema_object_type=equals:<type> --filter
+schema=not_equals:<newest-url> --all --json`.
+
 ## Reading the envelope
 
 Each invocation prints one JSON object:
@@ -181,19 +226,30 @@ Each invocation prints one JSON object:
   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?, moved_from?}`, action ∈ create/
-  update/revision/delete/move). A `move` is a file that took over a resource
-  from a removed one (`moved_from`). Plan rows preview; apply rows report, with
-  the resulting platform ids. Use it to verify an edit did what you intended.
-  `data.unsupported_deletions` counts removed files whose resource cannot be
-  deleted yet (they are kept, and are not part of `total`); on `apply` the files
-  are listed in `data.unsupported_deletion_files`.
-- `apply` leaves the files under `.zitadel/` as written: what the server stores
-  is never written back, and a field a file leaves out reads as the server's
-  default, so `plan` reports no change after an `apply`. `data.files_updated`
-  lists the one rewrite: a flow whose `user_schema` pinned a schema revision id
-  the apply superseded, re-pinned to the new revision's id.
+- `deploy` emits `data.content_hash` (the release digest), `data.origins`
+  (the origins it went live on) and `data.resources` (how many it pinned). A
+  re-run on unchanged config returns the same digest. Use it to confirm what
+  went live.
+- `preview` is `deploy` for a pull-request build: it deploys the release to the
+  build's preview URLs (from the platform, or `--origin`) for `--ttl` and emits
+  `data.previews` plus `data.release_env` (the `NEXT_PUBLIC_ZITADEL_RELEASE`
+  line to pin). It uses `ZITADEL_PROJECT_SECRET` until the server accepts the narrower preview token (#1575), never the other credential, and
+  outside a preview or development build it is a no-op — even with an explicit
+  `--origin`, which selects targets but never authorizes a preview deploy. A CI
+  build other than Vercel or Netlify must set `ZITADEL_ENV=preview`, or it is
+  skipped too. `preview list` and `preview rm <url>` read and end live previews.
+- `deployment rollback` emits `data.release_id` (the release live again),
+  `data.origins` and `data.pointers`, the `{kind, handle, revision_id}`
+  revisions that release pins; the `schema` one is what new registrations use.
+  Users keep their schema revision and attributes: a rollback does not migrate
+  them back. Without `data.pointers`, a warning says the release could not be
+  read.
+- `deploy --dry-run` and `deploy` emit `data.diff`, the git diff the terminal
+  shows, against the live release's commit (`diff.against`): `diff.files` holds
+  one `{path, status, previous_path?, patch}` per changed file (`status` is
+  `added`, `modified`, `deleted`, `renamed` or `copied`; `patch` is its unified
+  diff). Review it before you deploy. `files` is `[]` when nothing changed and
+  `null` when there is nothing to diff against, with `diff.note` saying why.
 - A write verb's `--dry-run` reports what it would send without calling the
   platform, so you can preview a mutation before making it.
 - `api` emits the response body as `data`, exactly as the API reference
@@ -208,11 +264,12 @@ Common error codes point at their own fix in `next_commands`:
   `details` often lists the missing or available values.
 - `E_CREDENTIAL_MISSING`: a connection's `client_id` or `client_secret` names a
   project variable that does not exist; `details.variable` is the name. Publish it
-  with `variables set NAME --project-level` (add `--secret` for the secret), then retry.
+  with `variable set NAME` (add `--secret` for the secret), then retry.
 - `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_NOT_FOUND`: an HTTP 404 — a missing resource, an operation the server's
+  version does not have (`details.body.code` is `req.not_found`), 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.
 
@@ -230,8 +287,9 @@ 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
+130: a command waiting on the server, or on an answer at a prompt, stops at
+once with `E_CANCELLED`, and any other command exits within a second, possibly
+without an envelope. In human mode a cancel prints no error block. An
 unknown command is handled by the CLI's help layer, not the envelope.
 
 ## Clarify before you configure
@@ -276,7 +334,7 @@ like. Read the current sets from `setup --help`, but know the traps:
   enabled**; `passkey-first` leads with a passkey. Neither one gives you
   password-only. If the developer does not want passkeys, turn them off
   yourself: set `x-auth-methods.passkey.enabled` to `false` in
-  `.zitadel/schemas/*.json`, then `apply`.
+  `.zitadel/schemas/*.json`, then `deploy`.
 
 Translate the developer's answers into the right axis values, then **verify
 against what actually deployed**: read the live schema back
@@ -291,13 +349,12 @@ 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
+flags, `--json`, the deploy flow, 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."
+- Avoid: "I ran `deploy` with `--non-interactive --json` and it 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
@@ -314,21 +371,51 @@ npx @zitadel/cli@latest doctor --non-interactive --json
 npx @zitadel/cli@latest start --non-interactive --json
 npx @zitadel/cli@latest setup --framework next --server local --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@latest deploy -m "<why this release changes>" --non-interactive --json
 ```
 
+`setup` commits the project it scaffolds: `git init` first when the directory
+is not yet a repository, then one commit, `chore: scaffold the project with
+zitadel setup`. A release records the commit it was built from and `deploy`
+diffs `.zitadel/` against it, so without this the first release carries no
+commit and the next deploy reports no diff.
+
+Setup refuses with `E_CONFLICT` when the repository already has uncommitted
+work, untracked files included, which `details.untracked` lists separately
+from `details.modified`. The commit covers the project directory, so it can
+only tell its own files from yours when the tree starts clean. Commit or stash
+first, then rerun. Only what `start` leaves is exempt: `.zitadel/local/` and
+the `.gitignore` line that ignores it. A connection under `.zitadel/idps/` is
+yours and is not exempt.
+
+Setup deploys nothing, and it does not need to: a project with no release
+resolves the newest revisions, which are the ones setup just uploaded, so
+sign-in already runs on `.zitadel/`. Deploying pins them into a release, which
+is what the server will require once that fallback goes (#1616). The publish
+step says so and names the command. `data.git` reports what setup did
+(`initialized`, and the `commit`, or null). `--no-git` skips both the refusal
+and the commit, and nothing prompts, so this is the same interactively and in
+CI.
+
 `setup` scaffolds into an empty directory, or patches an existing app project
 where it detects a framework. What `start` leaves in a directory —
 `.zitadel/local/` and the `.gitignore` line that ignores it — still counts as
 empty, so the golden path runs `setup` right after `start` in the same
-directory. Any other non-empty directory stops setup with a hint to pass
-`--force`. Pass it only for a directory whose contents may be replaced: files
+directory. A `--cwd` that does not exist yet counts as empty too: setup creates
+it with the app, and removes it again when setup fails before the app is kept.
+A `--cwd` that is a file fails with `E_VALIDATION`. Any other non-empty
+directory stops setup with a hint to pass `--force`. Pass it only for a
+directory whose contents may be replaced: files
 the new app also has, such as `package.json`, are overwritten. Without a
 terminal `setup` cannot ask which framework to scaffold, so pass `--framework`;
 the error lists the choices in `details.frameworks`. `setup --dry-run` creates
 no app: where it would scaffold one, it previews the project, and
 `data.files_written` is empty, because those files depend on the generated app.
+`setup` also writes and publishes the password policy
+(`.zitadel/policies/auth.factor.password.set.json`) with a minimum length of
+15, NIST's minimum for password-only sign-in and the wizard's default. Pass
+`--password-min-length <n>` only when the user asks for another value (`0` sets
+none), and give test users passwords at least that long.
 When setup fails after scaffolding a new app, before its default schema and
 flow are uploaded, it removes the app again and puts back what the directory
 held, so rerunning the same `setup` starts over.
@@ -347,15 +434,22 @@ replaces a file at a path setup writes, but not the app's root component or
 request boundary at another path.
 
 The app may also live in a subdirectory of the one `start` ran in: `setup`,
-`console`, `--server local` and `doctor` read `.zitadel/local/` from the working
+`console`, `logs`, `--server local` and `doctor` 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 too. `doctor` checks that
 server and its port, but runs its project checks in the working directory, so run
 it from the app. When that server is unhealthy it suggests `start` and
 `reset --force` with `--cwd` set to the directory that holds it (when that path needs
 shell quoting the commands are left out, the hint names the directory, and
-`doctor --json` returns the argument lists in `details.suggested_args` to run as they are). `stop`,
-`reset`, `logs` and `status` read only the working directory's
+`doctor --json` returns the argument lists in `details.suggested_args` to run as they are).
+The hint says the server is the parent's and that `reset --force` deletes the data in that
+directory, and it adds a plain `start`, which gives the working directory a server of its own
+because `start` does not look in parents; a healthy parent server is reported in the `runtime`
+check as started in the parent folder. A
+local server is healthy once its `/readyz` answers, which takes its database
+answering too: `start` waits for that, and the commands that read a server
+treat one whose database does not answer as unhealthy. `stop`,
+`reset` and `status` read only the working directory's
 `.zitadel/local/`, so run them where `start` ran. 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
@@ -363,10 +457,14 @@ 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.
 
-When `setup --sso` or `sso enable` adds a social sign-in provider, the user
+For a project set up against a hosted server, `doctor` checks no local
+runtime, unless a local server was started in its directory or a parent, or
+`--port`, `--runtime` or `--image` asks about one.
+
+When `setup --sso` or `auth-method sso enable` adds a social sign-in provider, the user
 must register the connection's redirect URI with the provider themselves: give
 them `data.sso[].callback_uri` from `setup`, or `data.callback_uri` from
-`sso enable`, verbatim. Each connection has its own URI, so a URI from another
+`auth-method sso enable`, verbatim. Each connection has its own URI, so a URI from another
 provider or an older CLI version does not work.
 
 After `setup`, follow `data.next_commands` to start the app. Prove the generated
@@ -374,9 +472,18 @@ auth flow in a visible browser by registering a unique user, logging out, loggin
 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.
 
-To move a set-up app to another dev port (the dev server exits with
-`EADDRINUSE`, or another app needs the port), run `setup --dev-port <port>` in
-the app; never change the port in one file by hand. In a directory with a
+When a step against the local server fails without saying why (the login says a
+sign-in provider "is not available right now", or a request returns 500), the
+server logged the cause. Read it with `logs --level warn --json`: `data.logs`
+holds the warnings and errors, and `--tail` counts only those lines. `logs
+--follow` streams the log for a person at a terminal, with warnings yellow and
+errors red; it refuses `--json`. `start`, and `doctor` when it finds the server
+running, name it in `data.next_actions`.
+
+To move a set-up app to another dev port (setup's `warnings` say the port is
+already in use, the dev server exits with `EADDRINUSE`, or another app needs
+the port), run `setup --dev-port <port>` in the app; never change the port in
+one file by hand. In a directory with a
 `zitadel.json`, `setup` returns `status: "skipped"` with `reason:
 "already-initialized"`, unless `--dev-port` is given: then it moves the app.
 It allows the new origin on the server first, and a refusal changes nothing.
@@ -399,6 +506,13 @@ than one:
   stdin when non-interactive. Any other OpenID Connect provider is
   `--provider custom` with `--slug`, `--display-name`, `--issuer` and optionally
   `--scopes` (default `openid profile email`).
+  In a terminal, a custom provider's settings you leave out are asked for, after
+  the checks that need no answer; a connection that already has that slug
+  supplies its own. A scripted, `--json`, `--dry-run` or `--non-interactive`
+  run must pass all three and gets an error naming the missing ones. After
+  writing a new connection the text output prints the claim mappings and names
+  the file to edit them in; `--json` does not carry them, so read the
+  connection file.
   An issuer on `http://localhost:<port>` (a test provider on this machine)
   works against a server `zitadel start` runs as a process: `start` sets
   `NEXTGEN_HTTPCLIENT_ALLOW_LIST=localhost,127.0.0.0/8,::1/128` unless
@@ -410,7 +524,11 @@ than one:
 
 The commands change only local files, apart from
 `auth-method sso enable`, which also stores the provider's credentials on the
-project. When they refuse, they write and publish nothing, on a dry run too.
+project. A provider added by `sso enable` is configured locally, not live: its
+`data.title` says so, `data.next_actions` says to deploy, and `data.next_commands`
+holds `deploy --dry-run` then `deploy`. Only run those once the provider's OAuth
+application exists. `data.title` claims the credentials are stored on the project
+only when they reached it. When they refuse, they write and publish nothing, on a dry run too.
 They refuse to disable a method a login flow still asks for, to change a method
 while a login flow has errors that prevent checking it, to enable password on a
 schema without `x-identifier`, to edit a value that is not the shape they edit,
@@ -423,15 +541,37 @@ and warns that no way to sign in would be left. A method that is enabled but not
 offered by any active flow is reported in `warnings` (and in `data.not_offered`
 for password and passkey). Every command reports `data.changed`, the
 project-relative files it wrote (on a dry run, the files it would write), empty
-when nothing changed. Follow `data.next_commands` (`plan`, `apply`, and
-`variables set` when a credential did not reach the project) to publish the
+when nothing changed. Follow `data.next_commands` (`deploy --dry-run`, `deploy`, and
+`variable set` when a credential did not reach the project) to publish the
 change. When a path or schema name would need shell quoting, `next_commands` is
 empty and `data.next_args` (or `details.suggested_args` on a refusal) holds the
 same commands as argument lists.
 
 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.
+then re-run `deploy`. See the reference below for driving the login UI
+and the config-sync details. The editor schemas in `.zitadel/meta/` are
+generated by the CLI, not config: never edit them. `doctor` warns when one is
+missing or outdated (after an upgrade that changed a dialect), and
+`doctor --fix` writes the current ones, unless the project pins a newer
+`@zitadel/*` version (run that version's `doctor --fix`) or a symlink is on
+the path; `deploy --dry-run` validates without them either way.
+
+## Claiming a project
+
+A project on a hosted server stays temporary until a person claims it, within
+14 days of `setup`. Claiming signs that person in with their own Zitadel
+account in a browser, so it is their step: hand them the link, and never open
+it yourself. Plain `claim` waits for the browser step and prints nothing on
+stdout until it ends, so run `claim --no-wait --non-interactive --json`
+instead. It returns at once with `data.claim_url`, the link to give the person
+verbatim, and `data.expires_at`, when it stops working (about 10 minutes).
+Then run the `claim --challenge-id …` command in `data.next_commands`: it
+waits for the person to finish, returns `data.dashboard_url`, and records the
+owning team in `.zitadel/secret`. When the link expires, or `--challenge-id`
+names one the platform does not know (`E_NOT_FOUND`), `next_commands` starts a
+new `--no-wait` link. A project that already has a team is `skipped` with
+`reason: "already-claimed"`; one past its 14 days fails with `E_VALIDATION`
+and no `next_commands`, since a new link cannot reopen it.
 
 ## Reference files
 
@@ -439,4 +579,4 @@ 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).
+  workflow (schemas, flows, branding, policies and their tests).

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

@@ -45,7 +45,8 @@ 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
+then re-run `deploy` (or `deploy --dry-run` to validate and preview the diff
+without publishing). 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
@@ -53,9 +54,10 @@ template referenced as `"liquid_template": { "$file": "./login.liquid" }`. Scaff
 `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
+is published as part of the next release when you `deploy`, and the login
+serves the newest release. `deploy` validates templates with the authoritative
+LiquidJS validator (and `deploy --dry-run` runs the same validation without
+publishing; `E_VALIDATION` lists rule ids such as `no-script-tag` and
 `mandatory-gates`; every template must keep a `{% mandatory_gates %}` tag,
 where the login adds any required field and the primary action the template
 left out). Asset URLs must be absolute `https://`; during development, images
@@ -67,17 +69,50 @@ directory. 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 flow names its schema by `objectType` in
-`user_schema` and runs against the schema's newest revision, so a schema revise
-needs no change to `user_schema`; one that removes or renames a property a step
-collects needs that step's `fields` updated, and `plan` checks only the flows it
-uploads. A login pinned by `flow-name` serves that flow's newest active
-revision; an unpinned login serves the newest active unscoped revision for its
-purpose in the project, whatever its flow's name. Older revisions stay active,
-so an `audience` added after a flow was applied without one doesn't take that
-earlier revision out of the running. Removing a flow file does not retire the
-flow. Managed files carry a marker comment; `eject` removes only
+revisioned like branding: an edit is published as a new immutable flow revision
+in the next `deploy`. A flow names its schema by `objectType` in `user_schema`
+and runs against the schema's newest revision, so a schema revise needs no
+change to `user_schema`; one that removes or renames a property a step
+collects needs that step's `fields` updated, and `deploy` checks each flow
+against the schema it names. A login pinned by `flow-name` serves that flow's
+newest active revision; an unpinned login serves the newest active unscoped
+revision for its purpose in the project, whatever its flow's name. Older
+revisions stay active, so an `audience` added after a flow was deployed
+without one doesn't take that earlier revision out of the running. Removing a
+flow file does not retire the
+flow. Operation policies live in `.zitadel/policies/`: one `<operation>.json`
+per guarded operation, named after its `operation`, holding
+`{"$schema": "../meta/policy.json", "operation": "auth.factor.password.set",
+"config": {"min_length": 15}}`. `deploy` checks each file against
+`.zitadel/meta/policy.json` (known operation, only the template's settings,
+within their bounds) and its name before anything is sent; settings that
+contradict each other (a `min_length` above `max_length`) are refused by the
+server's release build with `rel.invalid`, the policy's entry carrying
+`pol.invalid`. A changed file publishes a new revision of the same policy,
+which applies the next time a password is set. A setting left out is off, and
+`"config": {}` switches every rule off. A sign-in or sign-up uses the policy
+the deployed release carries, so deploying without the file switches it off
+there; a password set through the API, or before the first deploy, uses the
+newest revision, which only `"config": {}` switches off. `policies list` and
+`policies get <id|operation>` read them back. A policy's cases live beside it
+in `<operation>.test.json` (`.zitadel/meta/policy-test.json`): each names an
+`input` in the operation's terms (`{"password": "…"}`), optional `facts` the
+operation would look up (`self_service`, `history_matches`), and the expected
+decision (`allowed`, optionally `code` and exactly the `violations`). The
+decision and rules hold in the login too; `code` is the API's answer, and a
+flow shows each rule as `error.x-auth-methods#password_<rule>` instead.
+`policies test [operation]` evaluates every case on the server against the
+sibling policy file, or with `--release <id>` against the revision that
+release pins; a missing policy is tested as none. It fails with `E_VALIDATION`
+(exit 3) when a case does not hold, `data`/`details` carrying `source`,
+`operations[].cases[]` (`name`, `passed`, `expected`, `actual`), `passed` and
+`failed`; with no test files it is `skipped` (`no-policy-tests`). `deploy`
+never carries test files. Until #2331, a release that pins no flow is tested
+with a warning: its sign-ins use the newest revisions instead. Write cases from
+what the user wants enforced; never invent expectations for them. `setup` writes and publishes
+the password policy with a `min_length` of 15; pass `--password-min-length <n>`
+only when the user asks for another value (`0` sets none). 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