fix: give --environment one meaning across the CLI

.changeset/drop-dead-environment-flag.md

@@ -0,0 +1,5 @@
+---
+"@zitadel/cli": minor
+---
+
+**Breaking:** remove `--environment` (`-e`) from `plan`, `apply` and the resource commands (`users`, `teams`, `sessions`, `events`, `grants`, `idps`, `projects`, `schemas`, `environments`, `releases`, `flow-definitions`, `branding`). It only accepted `development`, `preview` or `production`, which are not the platform's environment names, and it never reached the platform: its one effect was to read a server URL from `environments.<name>.server` in `zitadel.json`, which nothing writes. Passing it now fails as an unknown flag; drop it from scripts. `--server`, `ZITADEL_API_BASE` and the top-level `server` in `zitadel.json` still choose the server. `--environment` now means one thing: a real environment on the platform, as the `variables` commands use it.

apps/cli/SKILLS.md

@@ -347,6 +347,10 @@ docker --image <ref>` remains the explicit image override for debugging.
 
 - `plan` — validate config and preview the sync diff without mutating anything.
 - `apply` — validate and upload repo config to the platform.
+- `plan`, `apply` and the resource commands take no `--environment`: they
+  work on the project's resources and do not select an environment.
+  `variables` is the only command group that addresses an environment; putting
+  config onto an environment is `deploy`'s job (ADR 035).
 - `plan` and `apply --dry-run` also emit `data.warnings`: non-blocking
   findings as `{path, rule, message}`, the same text the human plan prints as
   `# warning:` lines and `apply` prints through stderr. They never fail a run.

apps/cli/src/commands/apply.ts

@@ -1,10 +1,8 @@
-import { Flags } from "@oclif/core";
 import { consola } from "consola";
 
 import { createZitadelClient } from "@zitadel/api/client";
 
 import { BaseCommand, CommandGroups, type JsonEnvelope } from "../lib/oclif";
-import { environmentSchema } from "../lib/environment";
 import {
   buildSyncPlan,
   collectPlanWarnings,
@@ -30,14 +28,6 @@ export default class Apply extends BaseCommand {
   static override description = "Validate and upload repo config to the platform.";
   static override group = CommandGroups.configuration;
   static override groupOrder = 2;
-  static override flags = {
-    environment: Flags.string({
-      char: "e",
-      description: "Target environment (default: development).",
-      options: [...environmentSchema.options],
-    }),
-  };
-
   async run(): Promise<JsonEnvelope> {
     const { flags } = await this.parse(Apply);
     await this.toMeta(flags);

apps/cli/src/commands/plan.ts

@@ -1,10 +1,8 @@
-import { Flags } from "@oclif/core";
 import { consola } from "consola";
 
 import { createZitadelClient } from "@zitadel/api/client";
 
 import { BaseCommand, CommandGroups, type JsonEnvelope } from "../lib/oclif";
-import { environmentSchema } from "../lib/environment";
 import {
   buildSyncPlan,
   collectPlanWarnings,
@@ -27,14 +25,6 @@ export default class Plan extends BaseCommand {
   static override description = "Validate config without mutation and preview the sync diff.";
   static override group = CommandGroups.configuration;
   static override groupOrder = 1;
-  static override flags = {
-    environment: Flags.string({
-      char: "e",
-      description: "Target environment (default: development).",
-      options: [...environmentSchema.options],
-    }),
-  };
-
   async run(): Promise<JsonEnvelope> {
     const { flags } = await this.parse(Plan);
     await this.toMeta(flags);

apps/cli/src/commands/resources.ts

@@ -1,4 +1,3 @@
-import { Flags } from "@oclif/core";
 import { createZitadelClient, type ZitadelClient } from "@zitadel/api/client";
 import {
   CreateGrantBody,
@@ -62,7 +61,6 @@ import type {
 } from "@zitadel/api/generated/model";
 import { consola } from "consola";
 
-import { environmentSchema } from "../lib/environment";
 import { CommandGroups } from "../lib/oclif/groups";
 import { ZitadelError } from "../lib/errors";
 import { buildResourceCommands, type ResourceRegistry } from "../lib/oclif/crud";
@@ -557,13 +555,6 @@ export const RESOURCES = {
  */
 export const RESOURCE_COMMANDS = buildResourceCommands<Platform>(RESOURCES, {
   operations: FILTER_OPERATIONS,
-  flags: {
-    environment: Flags.string({
-      char: "e",
-      description: "Target environment (default: development).",
-      options: [...environmentSchema.options],
-    }),
-  },
   connect: async ({ cwd, source }) => {
     const secret = await readZitadelSecret(cwd);
     // Which project and server a verb is about is worth stating to a human, and

apps/cli/src/lib/environment.ts

@@ -1,22 +1,7 @@
-import { z } from "zod";
-
 import type { ZitadelClient } from "@zitadel/api/client";
 
 import { ZitadelError } from "./errors";
 
-/**
- * CLI-side deployment environment. Not an API model — it gates which
- * `zitadel.json` environment block and server the commands target.
- * Project request/response shapes live in `@zitadel/api`
- * (generated from the OpenAPI spec).
- *
- * This is the older of the CLI's two meanings of "environment", used by
- * `plan`, `apply` and the resource commands to pick a server. It does not match
- * the platform's environments, which are open DNS-style names seeded as `dev`,
- * `staging` and `prod`; {@link assertEnvironmentName} is the grammar for those.
- */
-export const environmentSchema = z.enum(["development", "preview", "production"]);
-
 /**
  * The platform's environment-name grammar, from `environment-name.yaml`: a
  * lowercase DNS-style label. Checked before any request so a malformed name

apps/cli/src/lib/oclif/base.ts

@@ -124,11 +124,10 @@ export abstract class BaseCommand extends Command {
   ): Promise<GlobalOptions> {
     const cwd = resolveCwd(typeof flags.cwd === "string" ? flags.cwd : undefined);
     const serverFlag = typeof flags.server === "string" ? flags.server : undefined;
-    const environment = typeof flags.environment === "string" ? flags.environment : "development";
     const source =
       options.resolveServer === false
         ? { value: options.source ?? "", origin: "default" as const }
-        : await resolveServer({ cwd, env: process.env, serverFlag, environment });
+        : await resolveServer({ cwd, env: process.env, serverFlag });
     const json = this.jsonEnabled();
     const isTTY = Boolean(process.stdout.isTTY && process.stdin.isTTY);
     const verbose = Boolean(flags.verbose);

apps/cli/src/lib/oclif/crud/fields.ts

@@ -36,7 +36,7 @@ export type BodyField = Readonly<{
 }>;
 
 /** Flags the write commands own; a body field of the same name stays raw-body only. */
-const RESERVED = new Set(["data", "file", "json", "cwd", "server", "force", "environment", "help"]);
+const RESERVED = new Set(["data", "file", "json", "cwd", "server", "force", "help"]);
 
 const kebab = (name: string): string => name.replaceAll("_", "-");
 

apps/cli/src/lib/oclif/crud/types.ts

@@ -219,7 +219,7 @@ export type ResourceCommandOptions<Ctx> = Readonly<{
   connect: (meta: GlobalOptions) => Promise<Ctx>;
   /** Filter operations the query endpoints accept (`equals`, `contains`, …). */
   operations: readonly string[];
-  /** Extra flags added to every generated command (e.g. an environment selector). */
+  /** Extra flags added to every generated command. */
   flags?: Interfaces.FlagInput;
   /** Wire vocabulary; each property falls back to {@link DEFAULT_WIRE}. */
   wire?: Partial<WireConventions>;

apps/cli/src/lib/oclif/environment-command.ts

@@ -52,13 +52,10 @@ export abstract class EnvironmentCommand extends BaseCommand {
   private projectLevel = false;
 
   /**
-   * Validate the owner flags, then build the invocation context without them.
+   * Validate the owner flags, then build the invocation context.
    *
-   * `--environment` names an owner on the one instance the CLI talks to; it is
-   * not a `zitadel.json` block. `BaseCommand.toMeta` passes a
-   * `flags.environment` to the server resolver, where a matching
-   * `environments.<name>.server` would redirect the request, so it is withheld
-   * and the server resolves as it does for a command with no such flag.
+   * `--environment` names an owner on the one instance the CLI talks to; it
+   * plays no part in choosing that instance.
    */
   protected override async toMeta(
     flags: Record<string, unknown>,
@@ -69,7 +66,7 @@ export abstract class EnvironmentCommand extends BaseCommand {
       this.requestedEnvironment = flags.environment;
     }
     this.projectLevel = flags["project-level"] === true;
-    return super.toMeta({ ...flags, environment: undefined }, options);
+    return super.toMeta(flags, options);
   }
 
   /**

apps/cli/src/lib/server.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 
 import { ZitadelError } from "./errors";
 import { resolveLocalServer } from "./local-server/runtime";
-import { isObject, parseJsonObject } from "./json";
+import { parseJsonObject } from "./json";
 
 /**
  * Server URL used when nothing else resolves. Also surfaced in hints and
@@ -19,26 +19,24 @@ export const DEFAULT_SERVER = "https://api.zitadel.cloud";
  */
 export type ResolvedServer = {
   value: string;
-  origin: "flag" | "env" | "config-env" | "config-top" | "default" | "local";
+  origin: "flag" | "env" | "config-top" | "default" | "local";
 };
 
 /**
  * Inputs to {@link resolveServer}. Passed explicitly (cwd, env) rather
  * than read from globals so resolution is pure and testable. `serverFlag`
- * and `environment` come from the parsed CLI invocation.
+ * comes from the parsed CLI invocation.
  */
 export type ResolveServerInput = {
   cwd: string;
   env: NodeJS.ProcessEnv;
   serverFlag?: string;
-  environment?: string;
 };
 
 /**
  * Resolves which server the CLI should target, applying a fixed
  * precedence: explicit `--server` flag, then `ZITADEL_API_BASE`, then the
- * selected environment block in `zitadel.json`, then the config's
- * top-level `server`, falling back to {@link DEFAULT_SERVER}. Every
+ * `server` in `zitadel.json`, falling back to {@link DEFAULT_SERVER}. Every
  * candidate is validated to a normalised origin; an invalid URL throws a
  * `ZitadelError` rather than silently falling through.
  */
@@ -52,14 +50,8 @@ export async function resolveServer(input: ResolveServerInput): Promise<Resolved
   }
 
   const config = await readConfig(input.cwd);
-  if (config) {
-    const envBranch = readEnvServer(config, input.environment);
-    if (envBranch) {
-      return validate(input.cwd, { value: envBranch, origin: "config-env" });
-    }
-    if (typeof config.server === "string") {
-      return validate(input.cwd, { value: config.server, origin: "config-top" });
-    }
+  if (typeof config?.server === "string") {
+    return validate(input.cwd, { value: config.server, origin: "config-top" });
   }
 
   return { value: DEFAULT_SERVER, origin: "default" };
@@ -105,21 +97,3 @@ async function readConfig(cwd: string): Promise<Record<string, unknown> | undefi
     throw error;
   }
 }
-
-function readEnvServer(
-  config: Record<string, unknown>,
-  environment: string | undefined,
-): string | undefined {
-  if (!environment) {
-    return undefined;
-  }
-  const envs = config.environments;
-  if (!isObject(envs)) {
-    return undefined;
-  }
-  const branch = envs[environment];
-  if (!isObject(branch)) {
-    return undefined;
-  }
-  return typeof branch.server === "string" ? branch.server : undefined;
-}

apps/cli/tests/unit/commands/apply.test.ts

@@ -87,6 +87,26 @@ describe("apply command pre-flight", () => {
     expect(json.code).toBe("E_VALIDATION");
     expect(json.message).toContain("Missing environment variables");
   });
+
+  it.each(["-e", "--environment"])("refuses %s, which addresses no environment", async (flag) => {
+    const cwd = await makeCwd({});
+
+    const res = await runCliForTest([
+      "apply",
+      flag,
+      "prod",
+      "--cwd",
+      cwd,
+      "--json",
+      "--server",
+      "https://api.zitadel.cloud",
+    ]);
+
+    expect(res.exitCode).toBe(3);
+    const json = parseJson(res.stdout) as { code: string; message: string };
+    expect(json.code).toBe("E_VALIDATION");
+    expect(json.message).toContain("Nonexistent flag");
+  });
 });
 
 const VALID_USER_SCHEMA = {

apps/cli/tests/unit/commands/plan.test.ts

@@ -132,4 +132,24 @@ describe("plan command", () => {
     expect(json.status).toBe("error");
     expect(json.code).toBe("E_VALIDATION");
   });
+
+  it.each(["-e", "--environment"])("refuses %s, which addresses no environment", async (flag) => {
+    const cwd = await makeProject();
+
+    const res = await runCliForTest([
+      "plan",
+      flag,
+      "prod",
+      "--cwd",
+      cwd,
+      "--json",
+      "--server",
+      "https://api.zitadel.cloud",
+    ]);
+
+    expect(res.exitCode).toBe(3);
+    const json = parseJson(res.stdout) as { code: string; message: string };
+    expect(json.code).toBe("E_VALIDATION");
+    expect(json.message).toContain("Nonexistent flag");
+  });
 });

apps/cli/tests/unit/commands/resources.test.ts

@@ -72,6 +72,28 @@ describe("resource registry", () => {
     }
   });
 
+  it("gives no generated command an --environment flag, since none addresses one", () => {
+    const generated = Object.entries(COMMANDS).filter(([id]) => id.split(":")[0] in RESOURCES);
+    expect(generated.length).toBeGreaterThan(0);
+    for (const [id, command] of generated) {
+      const flags = { ...command.baseFlags, ...command.flags };
+      expect(Object.keys(flags), id).not.toContain("environment");
+      expect(
+        Object.values(flags).map((flag) => flag.char),
+        id,
+      ).not.toContain("e");
+    }
+  });
+
+  it("refuses -e on a generated command before any request", async () => {
+    const cwd = await makeProject();
+    const res = await run(cwd, ["users", "list", "-e", "prod"]);
+    expect(res.exitCode).toBe(3);
+    const json = parseJson(res.stdout) as { code: string; message: string };
+    expect(json.code).toBe("E_VALIDATION");
+    expect(json.message).toContain("Nonexistent flag");
+  });
+
   it("advertises only filter and sort fields the generated query schemas accept", () => {
     // Only a spec carrying `body` is sent as a structured query, and that body
     // is the authority on which fields exist. A GET list has no such schema,

apps/cli/tests/unit/lib/environment.test.ts

@@ -4,32 +4,10 @@ import type { ZitadelClient } from "@zitadel/api/client";
 
 import {
   assertEnvironmentName,
-  environmentSchema,
   listEnvironmentNames,
   ownerLabel,
 } from "../../../src/lib/environment";
 
-describe("environmentSchema", () => {
-  it.each(["development", "preview", "production"])("parses the valid environment %s", (value) => {
-    expect(environmentSchema.parse(value)).toBe(value);
-  });
-
-  it("rejects an unknown environment string", () => {
-    const result = environmentSchema.safeParse("staging");
-    expect(result.success).toBe(false);
-  });
-
-  it("rejects a non-string value", () => {
-    const result = environmentSchema.safeParse(42);
-    expect(result.success).toBe(false);
-  });
-
-  it("rejects an empty string", () => {
-    const result = environmentSchema.safeParse("");
-    expect(result.success).toBe(false);
-  });
-});
-
 describe("assertEnvironmentName", () => {
   it.each(["dev", "prod", "staging", "staging-eu", "a".repeat(63)])(
     "accepts the platform-legal name %s",