fix: harden local setup and login automation

Author: fforootd

.changeset/README.md

@@ -29,7 +29,7 @@ The repo is currently in changesets **prerelease mode** with the `alpha` tag (se
 - `changeset version` cuts versions like `0.1.0-alpha.0`, `0.1.0-alpha.1`, …
 - Public packages are in one fixed group, so an alpha train uses the same
   version across `@zitadel/cli`, SDKs, components, and generated API packages.
-- `changeset publish` publishes them under the **`alpha`** npm dist-tag, **not** `latest`. So `npm install @zitadel/cli` keeps resolving the last stable release; consumers opt into prereleases with `@zitadel/cli@alpha`.
+- `changeset publish` publishes them under the **`alpha`** npm dist-tag. During the public alpha, the release workflow also promotes only `@zitadel/cli` to `latest` so bare `npx @zitadel/cli` reaches the supported tester workflow. Other public packages stay opt-in via `@alpha` or exact alpha versions.
 - A package that has never had a stable release is published to `latest` on its first publish (changesets behaviour), then to `alpha` thereafter until it has a stable release.
 
 To leave alpha and cut a stable `latest` release:

.changeset/harden-local-setup-automation.md

@@ -0,0 +1,6 @@
+---
+"@zitadel/cli": patch
+"@zitadel/components": patch
+---
+
+Harden local setup guidance, Next 16 scaffolding, and login form automation.

.github/workflows/ci.yml

@@ -864,6 +864,26 @@ jobs:
           # repository is public.
           NPM_CONFIG_PROVENANCE: "false"
 
+      - name: Promote CLI alpha to npm latest
+        if: ${{ steps.changesets.outputs.published == 'true' }}
+        env:
+          NPM_CONFIG_PROVENANCE: "false"
+        run: |
+          set -euo pipefail
+          version="$(node -p "require('./apps/cli/package.json').version")"
+          node --input-type=module - "$version" <<'NODE'
+          const version = process.argv[2];
+          if (!/^\d+\.\d+\.\d+-alpha\.\d+$/.test(version)) {
+            throw new Error(`expected an alpha CLI version, got ${version}`);
+          }
+          NODE
+          # Temporary public-alpha exception: the CLI is the tester entrypoint,
+          # so bare `npx @zitadel/cli` must reach the supported local workflow.
+          # Keep `alpha` as the canonical prerelease tag, and do not move
+          # `latest` for SDKs/components, Docker images, or GitHub Releases.
+          npm dist-tag add "@zitadel/cli@$version" alpha
+          npm dist-tag add "@zitadel/cli@$version" latest
+
       - name: Restore changesets after publish decision
         run: git restore -- .changeset
 

apps/cli-journey-e2e/scripts/prepare-next-app.mjs

@@ -18,6 +18,7 @@ export async function prepareNextApp(options = {}) {
   const appDir = resolve(env.JOURNEY_APP_DIR ?? join(outputDir, "myapp"));
   const registryUrl = env.JOURNEY_REGISTRY_URL ?? defaultRegistryUrl;
   const appUrl = env.JOURNEY_APP_URL ?? defaultAppUrl;
+  const zitadelPort = optionalPort(env.JOURNEY_ZITADEL_PORT, "JOURNEY_ZITADEL_PORT");
   const fs = {
     appendFile: options.appendFile ?? appendFile,
     mkdir: options.mkdir ?? mkdir,
@@ -46,7 +47,7 @@ export async function prepareNextApp(options = {}) {
       outputDir,
       runCapture: runCaptureFn,
       step: "doctor",
-      stepArgs: ["doctor"],
+      stepArgs: withPort(["doctor"], zitadelPort),
       writeFile: fs.writeFile,
     });
     startJson = await runCliJsonStep({
@@ -56,7 +57,7 @@ export async function prepareNextApp(options = {}) {
       outputDir,
       runCapture: runCaptureFn,
       step: "start",
-      stepArgs: ["start"],
+      stepArgs: withPort(["start"], zitadelPort),
       writeFile: fs.writeFile,
     });
     setupJson = await runCliJsonStep({
@@ -225,6 +226,20 @@ function npmEnvironment(env, registryUrl) {
   };
 }
 
+function optionalPort(value, name) {
+  if (!value) return undefined;
+  const port = Number(value);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`${name} must be a TCP port, got ${value}`);
+  }
+  return port;
+}
+
+function withPort(args, port) {
+  if (!port) return args;
+  return [...args, "--port", String(port)];
+}
+
 function runCapture(command, args, options) {
   return new Promise((resolveRun, reject) => {
     const child = spawn(command, args, {

apps/cli-journey-e2e/scripts/prepare-next-app.test.mjs

@@ -20,6 +20,7 @@ test("prepares the customer local setup journey in the app root", async () => {
         JOURNEY_REGISTRY_URL: registryUrl,
         JOURNEY_SDK_NEXT_PACKAGE: "@zitadel/sdk-next",
         JOURNEY_WORK_DIR: workDir,
+        JOURNEY_ZITADEL_PORT: "18080",
         ZITADEL_LOCAL_IMAGE: image,
       },
       logMetadata: false,
@@ -32,7 +33,7 @@ test("prepares the customer local setup journey in the app root", async () => {
           await mkdir(join(options.cwd, ".zitadel/local"), { recursive: true });
           await writeFile(
             join(options.cwd, ".zitadel/local/runtime.json"),
-            `${JSON.stringify({ server_url: "http://localhost:8080" })}\n`,
+            `${JSON.stringify({ server_url: "http://localhost:18080" })}\n`,
           );
         }
         return {
@@ -45,21 +46,25 @@ test("prepares the customer local setup journey in the app root", async () => {
 
     const appDir = join(workDir, "myapp");
     assert.equal(metadata.appDir, appDir);
-    assert.equal(metadata.localRuntimeUrl, "http://localhost:8080");
+    assert.equal(metadata.localRuntimeUrl, "http://localhost:18080");
     assert.deepEqual(
       calls.map((call) => call.args),
       [
         [
           "--yes",
           "@zitadel/cli@alpha",
           "doctor",
+          "--port",
+          "18080",
           "--non-interactive",
           "--json",
         ],
         [
           "--yes",
           "@zitadel/cli@alpha",
           "start",
+          "--port",
+          "18080",
           "--non-interactive",
           "--json",
         ],
@@ -202,11 +207,12 @@ async function writeGeneratedApp(appDir, registryUrl) {
 
 function okEnvelope(args) {
   const command = args[2];
+  const port = args.includes("--port") ? args[args.indexOf("--port") + 1] : "8080";
   if (command === "start") {
-    return { status: "ok", data: { urls: { api: "http://localhost:8080" } } };
+    return { status: "ok", data: { urls: { api: `http://localhost:${port}` } } };
   }
   if (command === "setup") {
-    return { status: "ok", data: { server: "http://localhost:8080" } };
+    return { status: "ok", data: { server: `http://localhost:${port}` } };
   }
   return { status: "ok", data: { ok: true } };
 }

apps/cli-journey-e2e/scripts/run-local.mjs

@@ -45,6 +45,7 @@ const composeLogPath = join(diagnosticsDir, "compose.log");
 const composeProjectName = `zitadel-journey-${process.pid}-${Date.now()}`;
 const registryPort = await resolvePort("JOURNEY_REGISTRY_PORT");
 const appPort = await resolvePort("JOURNEY_APP_PORT", 3000);
+const zitadelPort = await resolvePort("JOURNEY_ZITADEL_PORT");
 const registryUrl = `http://127.0.0.1:${registryPort}`;
 const appUrl = `http://localhost:${appPort}`;
 const cliPackage = await packageName("apps/cli");
@@ -101,6 +102,7 @@ try {
     env: {
       ...process.env,
       JOURNEY_APP_URL: appUrl,
+      JOURNEY_ZITADEL_PORT: String(zitadelPort),
       JOURNEY_REGISTRY_URL: registryUrl,
       JOURNEY_WORK_DIR: workDir,
       NPM_CONFIG_USERCONFIG: verdaccioNpmrcPath,

apps/cli-journey-e2e/src/user-journey.spec.ts

@@ -1,4 +1,4 @@
-import { expect, test, type Page } from "@playwright/test";
+import { expect, test, type Locator, type Page } from "@playwright/test";
 
 test.describe.configure({ mode: "serial" });
 
@@ -196,11 +196,11 @@ async function expectRegistrationChoice(page: Page): Promise<void> {
 }
 
 async function fillEmail(page: Page, email: string): Promise<void> {
-  await page.getByLabel(/email/i).first().fill(email);
+  await fieldControl(page, "email", /email/i).fill(email);
 }
 
 async function fillEmailIfVisible(page: Page, email: string): Promise<void> {
-  const emailField = page.getByLabel(/email/i).first();
+  const emailField = fieldControl(page, "email", /email/i);
   if (await emailField.isVisible().catch(() => false)) {
     await emailField.fill(email);
   }
@@ -224,11 +224,11 @@ async function fillFieldIfVisible(
 }
 
 async function fillPassword(page: Page, password: string): Promise<void> {
-  await page.getByLabel(/password/i).first().fill(password);
+  await fieldControl(page, "password", /password/i).fill(password);
 }
 
 async function isPasswordVisible(page: Page): Promise<boolean> {
-  return page.getByLabel(/password/i).first().isVisible().catch(() => false);
+  return fieldControl(page, "password", /password/i).isVisible().catch(() => false);
 }
 
 async function expectSessionCleared(page: Page): Promise<void> {
@@ -253,7 +253,12 @@ async function clickAction(
 ): Promise<void> {
   let locator = page.getByRole("button", { name }).or(page.getByRole("link", { name }));
   for (const actionName of actionNames) {
-    locator = actionLocator(page, actionName).or(locator);
+    locator = page
+      .getByTestId(`zitadel-action-${actionName}-button`)
+      .or(page.getByTestId(`zitadel-action-${actionName}`))
+      .or(page.getByTestId(`zitadel-action-${actionName}-link`))
+      .or(actionLocator(page, actionName))
+      .or(locator);
   }
   await locator.first().click();
 }
@@ -262,6 +267,15 @@ function actionLocator(page: Page, actionName: string) {
   return page.locator(`zl-button[action="${actionName}"], [data-action="${actionName}"]`);
 }
 
+function fieldControl(page: Page, fieldName: string, label: RegExp): Locator {
+  return page
+    .getByTestId(`zitadel-field-${fieldName}`)
+    .locator("input")
+    .or(page.locator(`zl-field[name="${fieldName}"]`).locator("input"))
+    .or(page.getByLabel(label))
+    .first();
+}
+
 function logoutLocator(page: Page) {
   return page
     .locator("zitadel-logout .signout-btn")

apps/cli/README.md

@@ -7,6 +7,10 @@ npx @zitadel/cli@alpha start
 npx @zitadel/cli@alpha setup --server local
 ```
 
+During the public alpha, bare `npx @zitadel/cli` resolves to the same tested
+alpha CLI. Use `@alpha` or an exact `0.1.0-alpha.N` selector in bug reports and
+automation when reproducibility matters.
+
 > **Beta.** This is the **next-generation Zitadel**, a ground-up rewrite of the platform. It is distinct from the established Zitadel at [github.com/zitadel/zitadel](https://github.com/zitadel/zitadel). APIs and CLI flags will change.
 
 ## Requirements
@@ -33,12 +37,13 @@ back to `ghcr.io/zitadel/nextgen:latest`. Override with `--image` or
 `ZITADEL_LOCAL_IMAGE` for advanced 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`, and
-`middleware.ts`, 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
-`http://localhost:3000/login` to see the login page.
+the current directory, scaffolds `app/login`, `app/register`, and `proxy.ts`
+for Next 16+ or `middleware.ts` for older Next versions, 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 `http://localhost:3000/login` to see the
+login page.
 
 For a reproducible tester report, use the exact alpha train from the GitHub
 Release:
@@ -58,6 +63,8 @@ passkey can sign in with either credential.
 
 - `zitadel doctor` — verify the local Docker runtime and generated project files
 - `zitadel status` — summarise the local Docker runtime and project
+- `zitadel plan` — validate config and preview sync changes without mutation
+- `zitadel apply` — validate and upload repo config to Zitadel
 - `zitadel eject` — remove what setup wrote (alias: `zitadel uninstall`)
 - `zitadel start|stop|logs|reset` — manage the local Docker runtime
 
@@ -68,12 +75,14 @@ passkey can sign in with either credential.
 
 <!-- commands -->
 
+- [`zitadel apply`](#zitadel-apply)
 - [`zitadel autocomplete [SHELL]`](#zitadel-autocomplete-shell)
 - [`zitadel commands`](#zitadel-commands)
 - [`zitadel doctor`](#zitadel-doctor)
 - [`zitadel eject`](#zitadel-eject)
 - [`zitadel help [COMMAND]`](#zitadel-help-command)
 - [`zitadel logs`](#zitadel-logs)
+- [`zitadel plan`](#zitadel-plan)
 - [`zitadel reset`](#zitadel-reset)
 - [`zitadel search`](#zitadel-search)
 - [`zitadel setup`](#zitadel-setup)
@@ -84,6 +93,33 @@ passkey can sign in with either credential.
 - [`zitadel version`](#zitadel-version)
 - [`zitadel which`](#zitadel-which)
 
+## `zitadel apply`
+
+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]
+
+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.
+      --debug                       Debug logging.
+      --dry-run                     Preview without mutating files or the platform.
+      --verbose                     Verbose logging.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Validate and upload repo config to the platform.
+```
+
 ## `zitadel autocomplete [SHELL]`
 
 Display autocomplete installation instructions.
@@ -246,6 +282,33 @@ DESCRIPTION
   Show local Zitadel server logs.
 ```
 
+## `zitadel plan`
+
+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]
+
+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.
+      --debug                       Debug logging.
+      --dry-run                     Preview without mutating files or the platform.
+      --verbose                     Verbose logging.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Validate config without mutation and preview the sync diff.
+```
+
 ## `zitadel reset`
 
 Delete the local Zitadel server runtime and data.

apps/cli/SKILLS.md

@@ -27,6 +27,10 @@ parse the result rather than scraping human output.
 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.
+
 ## Reading the envelope
 
 Each invocation prints one JSON object:

apps/cli/src/commands/apply.ts

@@ -19,10 +19,6 @@ import { readZitadelSecret } from "../lib/project";
  */
 export default class Apply extends BaseCommand {
   static override description = "Validate and upload repo config to the platform.";
-  // Temporarily hidden while we collapse the dev workflow around `setup`'s
-  // auto-apply. The logic stays wired up so re-exposing this command is a
-  // one-line flip when we settle on the surface area.
-  static override hidden = true;
   static override flags = {
     environment: Flags.string({
       char: "e",