@zitadel/cli 0.3.0 → 0.4.0

package/oclif.manifest.json

@@ -425,7 +425,7 @@
         },
         "message": {
           "char": "m",
-          "description": "A short summary of what this release changes.",
+          "description": "A short summary of what this release changes. Defaults to the pull request's title or the current commit's subject.",
           "name": "message",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -868,7 +868,8 @@
       "examples": [
         "<%= config.bin %> preview",
         "<%= config.bin %> preview --origin https://acme-git-sso-acmeinc.vercel.app",
-        "<%= config.bin %> preview --ttl 24h"
+        "<%= config.bin %> preview --ttl 24h",
+        "<%= config.bin %> preview -m 'add phone_number to human-user'"
       ],
       "flags": {
         "json": {
@@ -961,6 +962,14 @@
           "multiple": false,
           "type": "option"
         },
+        "message": {
+          "char": "m",
+          "description": "A short summary of what this release changes. Defaults to the pull request's title or the current commit's subject.",
+          "name": "message",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "strict": {
           "description": "Fail instead of warning when no preview credential (ZITADEL_PROJECT_SECRET) is set.",
           "name": "strict",
@@ -3050,6 +3059,14 @@
           "name": "force",
           "allowNo": false,
           "type": "boolean"
+        },
+        "message": {
+          "char": "m",
+          "description": "A short summary of why this rolls back.",
+          "name": "message",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -4157,6 +4174,88 @@
       "strict": true,
       "group": "Configuration and releases"
     },
+    "skills:add": {
+      "aliases": [],
+      "args": {},
+      "description": "Add the Zitadel agent skills to this project.\n\nAdds the skills of this CLI's version to .agents/skills, which most coding agents read, and to .claude/skills for Claude Code. Run it again after updating the CLI to replace them with the new version's.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --cwd my-app"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "cwd": {
+          "char": "c",
+          "description": "Project directory to operate on.",
+          "name": "cwd",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "server": {
+          "char": "s",
+          "description": "Override the resolved server URL.",
+          "name": "server",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "non-interactive": {
+          "char": "n",
+          "description": "Disable prompts. Required when scripting or running as an agent.",
+          "name": "non-interactive",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "dry-run": {
+          "description": "Preview without mutating files or the platform.",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "char": "v",
+          "description": "Verbose logging.",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "debug": {
+          "description": "Debug logging.",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "color": {
+          "description": "Colorize human output. Disable with --no-color; NO_COLOR and FORCE_COLOR are honored too.",
+          "name": "color",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "telemetry": {
+          "description": "Send anonymous usage analytics. Disable with --no-telemetry.",
+          "name": "telemetry",
+          "allowNo": true,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "skills:add",
+      "pluginAlias": "@zitadel/cli",
+      "pluginName": "@zitadel/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "group": "Getting started",
+      "groupOrder": 5
+    },
     "variable:set": {
       "aliases": [],
       "args": {
@@ -9409,5 +9508,5 @@
       "group": "Configuration and releases"
     }
   },
-  "version": "0.3.0"
+  "version": "0.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zitadel/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agent-friendly Zitadel CLI",
   "homepage": "https://github.com/zitadel/nextgen/tree/main/apps/cli#readme",
   "bugs": {
@@ -113,6 +113,9 @@
       },
       "api": {
         "description": "Call any operation of the Zitadel API."
+      },
+      "skills": {
+        "description": "Give coding agents the Zitadel skills."
       }
     }
   },
@@ -127,9 +130,9 @@
     "@oclif/plugin-search": "^1.2.50",
     "@oclif/plugin-version": "^2.2.46",
     "@oclif/plugin-which": "^3.2.55",
-    "@zitadel/api": "0.3.0",
-    "@zitadel/config": "0.3.0",
-    "@zitadel/server": "0.3.0",
+    "@zitadel/api": "0.4.0",
+    "@zitadel/config": "0.4.0",
+    "@zitadel/server": "0.4.0",
     "ajv": "^8.20.0",
     "consola": "^3.4.2",
     "magicast": "^0.5.3",
@@ -148,7 +151,7 @@
     "@types/wrap-ansi": "^3.0.0",
     "@vitest/coverage-v8": "^4.1.11",
     "@zitadel/api-mock": "0.0.0",
-    "@zitadel/sdk-next": "0.3.0",
+    "@zitadel/sdk-next": "0.4.0",
     "@zitadel/vitest-config": "0.0.0",
     "msw": "^2.14.6",
     "oclif": "^4.17.46",

package/skills/zitadel-cli/SKILL.md

@@ -47,6 +47,13 @@ by declared range or installed release, with `E_UNSUPPORTED_PROJECT_SHAPE`
 left the project untouched. The message names the minimum and the hint says to
 upgrade, so upgrade the app and rerun rather than retrying.
 
+The CLI ships this skill and the other Zitadel skills. `skills add` puts the
+ones of the version that runs it into the project's `.agents/skills/`, and into
+`.claude/skills/` when Claude Code is installed or the project has a `.claude/`
+folder, replacing older copies. After moving the app to a newer CLI, run it
+with that version so the skills describe it. It talks to no server and asks
+nothing; `data.skills` and `data.directories` say what it added where.
+
 ## Using the CLI
 
 - **Drive it non-interactively.** Always pass `--non-interactive --json` (short:
@@ -96,6 +103,9 @@ upgrade, so upgrade the app and rerun rather than retrying.
   `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`.
+  `ZITADEL_URL` and `--server` are the server's origin: the API lives under
+  `/api/v1` there, which the CLI adds (and drops from a URL that already ends
+  in it).
 - **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
@@ -137,8 +147,9 @@ upgrade, so upgrade the app and rerun rather than retrying.
 - **Calling an operation no command covers.** `zitadel api <operation>` calls
   any operation of the API with the resolved server and `.zitadel/secret`.
   Name it by its `operationId` (`queryUsers`, as the API reference and
-  `@zitadel/api` spell it) or by its path (`/users/query`; `-X` picks the
-  method where a path has several). Path parameters follow as arguments, in
+  `@zitadel/api` spell it) or by its path as the spec has it (`/users/query`,
+  which the server serves at `/api/v1/users/query`; a path copied with the
+  prefix works too, and `-X` picks the method where a path has several). Path parameters follow as arguments, in
   path order; a `project_id` left out is the project's own. `-F name=value`
   (or `name:=json`) sets a query parameter when the operation declares one by
   that name, else a dot path into the body, typed by the operation's schema;
@@ -238,6 +249,15 @@ Each invocation prints one JSON object:
   `--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.
+- `deploy` and `preview` record `-m` on the release and the deployment. Omitted,
+  they use a GitHub pull request's title, Vercel's commit message, or a clean
+  worktree's commit subject; with none, a non-interactive `deploy` fails. A
+  blank `-m` is refused. A release keeps the message of
+  the run that first built its content, usually the pull request's `preview`.
+  `deployment rollback -m` records why on the rollback.
+- `deployment get <id>` emits the deployment as the API serves it; on a
+  terminal it also shows the variables the deployment froze, secrets masked.
+  Read them as JSON with `variable resolve`.
 - `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.
@@ -248,7 +268,8 @@ Each invocation prints one JSON object:
   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
+  diff), including rapid same-size edits and untracked configuration files.
+  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.
@@ -268,13 +289,18 @@ Common error codes point at their own fix in `next_commands`:
 - `E_LOCAL_SERVER_NOT_RUNNING`: start the local runtime, then retry with
   `--server local`.
 - `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
+  version does not have (`details.body.code` is `req.not_found`; a server
+  from before the API moved under `/api/v1` answers every call so), 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.
+when piped or `--plain`); `--json` is unaffected and remains the contract. A
+human run lists its next steps under `Next:` after its result (`setup` shows
+them in its summary box instead); where stdout is data a script reads (a piped
+or `--plain` list, a resource's created or updated JSON) they go to stderr, so
+stdout holds only that data.
 
 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
@@ -380,20 +406,32 @@ 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.
 
+Then setup deploys `.zitadel/` to the app's origin, so the sign-in it asks you
+to verify is served the release it built. `data.deployment` carries the
+`release_id`, `content_hash`, `deployment_id` and `origins`, and is null on
+`--dry-run` or when the deploy failed. A failed deploy is a warning, never a
+failed setup, and `data.next_commands` then leads with the `deploy` that fixes
+it.
+
 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
+only tell its own files from yours when the tree starts clean. It never
+commits `.env*` files (other than `.env.example`), `.zitadel/secret` or
+`.zitadel/local/`, whatever their case. 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.
+yours and is not exempt. During a merge, rebase, cherry-pick, revert or bisect,
+or on a detached HEAD, setup refuses with `E_CONFLICT` before it writes
+anything, naming what stops the commit.
 
 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
+step says so and names the command. `data.git` reports what setup did:
+`initialized` when it ran `git init`, even if the commit then failed, 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.
 
@@ -555,6 +593,21 @@ 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.
+`deploy`, `preview` and `release create`, `--dry-run` included, check the
+shape of `.zitadel/` locally before anything is written, and fail with
+`E_VALIDATION` listing each problem by field and by the schema's or flow's
+handle (a policy by its file). The server still applies its own release rules
+when the build is submitted, such as handles being unique, so a passing dry run
+does not promise the release is accepted.
+
+An SPA's dev proxy (`vite.config.*`, Angular's `proxy.conf.cjs`) keeps the
+app's session in a cookie of its own project, `zitadel_session_<project id>`
+on `http://localhost` and `__Host-zitadel_session_<project id>` over https.
+`doctor` fails (`managed-files`, `outdated managed config wiring`) on the
+session-cookie hooks a CLI wrote before these names: the server no longer
+reads the cookies they keep. `doctor --fix` replaces hooks that are as the CLI
+wrote them; ones changed by hand must be updated by hand, which the failure
+says. Browsers signed in before the change sign in again.
 
 ## Claiming a project