feat(version): implement --version flag and version subcommand

Closes PRO-174.

Adds two surfaces over the same model:

- `prisma-cli --version` — universal early-exit utility flag at the root.
  Prints `prisma-cli <version>` to stdout in human mode; emits the standard
  success envelope (`command: "version"`, `result: {version}`) when
  combined with `--json`. Requires no auth, no project context, no network.

- `prisma-cli version` — top-level subcommand (peer to auth / branch /
  project / app) that uses the `show` output pattern. Reports the full
  environment block: CLI name + version, Node version, OS platform/arch,
  best-effort invocation label (bunx | npx | global | dev | unknown).

Implementation:

- New `lib/version.ts` reads the bundled package metadata via
  `createRequire(import.meta.url)` so it works under both tsx dev mode and
  the tsdown-unbundled `dist/` output. Throws `VERSION_UNAVAILABLE`
  (defensive; not expected) if metadata cannot be read.
- New `controllers/version.ts`, `presenters/version.ts`, `commands/version/`
  follow the same controller / presenter / command shape as `auth`.
- New `types/version.ts` defines `VersionResult` and `VersionInvocation`.
- `cli.ts` intercepts `--version` in argv before commander dispatches
  (mirrors the existing bare-help short-circuit). The bare-help resolver
  now skips leaf commands so `prisma-cli version` runs its action instead
  of being treated as a group-help command.
- `shell/command-meta.ts` registers the `version` descriptor.
- `shell/global-flags.ts` adds `--version` to `COMPACT_GLOBAL_OPTION_FLAGS`
  so help rendering still surfaces the "Global options:" header at the
  program root.

Tests:

- `tests/version.test.ts` — 8 cases covering the flag, the subcommand,
  both with `--json`, no-auth/no-project/no-network preconditions, help
  inclusion, and `--version` overriding subcommand parsing when both
  appear in argv.

All 178 existing + new tests pass. Build clean. No regressions on auth,
project, branch, or app surfaces.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: luanvdw

packages/cli/src/cli.ts

@@ -1,16 +1,22 @@
 import process from "node:process";
 
-import { Command, CommanderError } from "commander";
+import { Command, CommanderError, Option } from "commander";
 
 import { createAppCommand } from "./commands/app";
 import { createAuthCommand } from "./commands/auth";
 import { createBranchCommand } from "./commands/branch";
 
 import { createProjectCommand } from "./commands/project";
+import { createVersionCommand } from "./commands/version";
+import { runVersion } from "./controllers/version";
+import { getCliName, getCliVersion } from "./lib/version";
 import { attachCommandDescriptor } from "./shell/command-meta";
+import { CliError } from "./shell/errors";
 import { addCompactGlobalFlags } from "./shell/global-flags";
+import { writeHumanError, writeJsonError, writeJsonSuccess } from "./shell/output";
 import { disposePromptState } from "./shell/prompt";
-import { configureRuntimeCommand, type CliRuntime } from "./shell/runtime";
+import { configureRuntimeCommand, createCommandContext, type CliRuntime } from "./shell/runtime";
+import { createShellUi } from "./shell/ui";
 
 export interface RunCliOptions extends Partial<CliRuntime> {
   argv?: string[];
@@ -22,6 +28,10 @@ export async function runCli(options: RunCliOptions = {}): Promise<number> {
   process.exitCode = 0;
 
   try {
+    if (runtime.argv.includes("--version")) {
+      return await handleVersionFlag(runtime);
+    }
+
     const bareHelpCommand = resolveBareHelpCommand(program, runtime.argv);
 
     if (bareHelpCommand) {
@@ -49,10 +59,13 @@ export function createProgram(runtime: CliRuntime): Command {
 
   addCompactGlobalFlags(program);
 
+  program.addOption(new Option("--version", "Print the CLI version and exit."));
+
   program
     .name("prisma")
     .showSuggestionAfterError();
 
+  program.addCommand(createVersionCommand(runtime));
   program.addCommand(createAuthCommand(runtime));
   program.addCommand(createBranchCommand(runtime));
   program.addCommand(createProjectCommand(runtime));
@@ -61,6 +74,54 @@ export function createProgram(runtime: CliRuntime): Command {
   return program;
 }
 
+async function handleVersionFlag(runtime: CliRuntime): Promise<number> {
+  const wantsJson = runtime.argv.includes("--json");
+  const output = { stdout: runtime.stdout, stderr: runtime.stderr };
+
+  try {
+    if (wantsJson) {
+      const context = await createCommandContext(runtime, buildVersionFlagFlags(runtime));
+      const success = await runVersion(context);
+      writeJsonSuccess(output, {
+        command: success.command,
+        result: { version: success.result.cli.version },
+        warnings: success.warnings,
+        nextSteps: success.nextSteps,
+      });
+      return 0;
+    }
+
+    const versionLine = `${getCliName()} ${getCliVersion()}`;
+    runtime.stdout.write(`${versionLine}\n`);
+    return 0;
+  } catch (error) {
+    if (error instanceof CliError) {
+      if (wantsJson) {
+        writeJsonError(output, "version", error);
+      } else {
+        const ui = createShellUi(runtime, buildVersionFlagFlags(runtime));
+        writeHumanError(output, ui, error, { trace: false });
+      }
+
+      return error.exitCode;
+    }
+
+    throw error;
+  }
+}
+
+function buildVersionFlagFlags(runtime: CliRuntime) {
+  return {
+    json: runtime.argv.includes("--json"),
+    quiet: false,
+    verbose: false,
+    trace: false,
+    yes: false,
+    interactive: undefined,
+    color: undefined,
+  };
+}
+
 function resolveBareHelpCommand(program: Command, argv: string[]): Command | null {
   if (argv.length === 0) {
     return program;
@@ -70,7 +131,19 @@ function resolveBareHelpCommand(program: Command, argv: string[]): Command | nul
     return null;
   }
 
-  return program.commands.find((command) => command.name() === argv[0]) ?? null;
+  const candidate = program.commands.find((command) => command.name() === argv[0]) ?? null;
+
+  if (!candidate) {
+    return null;
+  }
+
+  // Group commands (with subcommands) print help when invoked bare.
+  // Leaf commands (no subcommands) own their own action and must execute.
+  if (candidate.commands.length === 0) {
+    return null;
+  }
+
+  return candidate;
 }
 
 function resolveRuntime(options: RunCliOptions): CliRuntime {

packages/cli/src/commands/version/index.ts

@@ -0,0 +1,29 @@
+import { Command } from "commander";
+
+import { runVersion } from "../../controllers/version";
+import { renderVersionSuccess } from "../../presenters/version";
+import { attachCommandDescriptor } from "../../shell/command-meta";
+import { runCommand } from "../../shell/command-runner";
+import { addGlobalFlags } from "../../shell/global-flags";
+import { configureRuntimeCommand, type CliRuntime } from "../../shell/runtime";
+import type { VersionResult } from "../../types/version";
+
+export function createVersionCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(configureRuntimeCommand(new Command("version"), runtime), "version");
+
+  addGlobalFlags(command);
+
+  command.action(async (options) => {
+    await runCommand<VersionResult>(
+      runtime,
+      "version",
+      options as Record<string, unknown>,
+      (context) => runVersion(context),
+      {
+        renderHuman: (context, descriptor, result) => renderVersionSuccess(context, descriptor, result),
+      },
+    );
+  });
+
+  return command;
+}

packages/cli/src/controllers/version.ts

@@ -0,0 +1,15 @@
+import { buildVersionResult } from "../lib/version";
+import type { CommandSuccess } from "../shell/output";
+import type { CommandContext } from "../shell/runtime";
+import type { VersionResult } from "../types/version";
+
+export async function runVersion(context: CommandContext): Promise<CommandSuccess<VersionResult>> {
+  const result = buildVersionResult(context.runtime.env, context.runtime.argv);
+
+  return {
+    command: "version",
+    result,
+    warnings: [],
+    nextSteps: [],
+  };
+}

packages/cli/src/lib/version.ts

@@ -0,0 +1,91 @@
+import { createRequire } from "node:module";
+import process from "node:process";
+
+import { CliError } from "../shell/errors";
+import type { VersionInvocation, VersionResult } from "../types/version";
+
+interface PackageMetadata {
+  name?: string;
+  version?: string;
+}
+
+const requireFromHere = createRequire(import.meta.url);
+
+function readPackageMetadata(): PackageMetadata {
+  try {
+    return requireFromHere("../../package.json") as PackageMetadata;
+  } catch {
+    return {};
+  }
+}
+
+export function getCliVersion(): string {
+  const pkg = readPackageMetadata();
+
+  if (!pkg.version) {
+    throw new CliError({
+      code: "VERSION_UNAVAILABLE",
+      domain: "cli",
+      summary: "CLI version metadata is missing from the installed package",
+      why: "The bundled package.json could not be read or did not contain a version field.",
+      fix: "Reinstall the CLI from the npm registry, or check your install path is intact.",
+      exitCode: 1,
+    });
+  }
+
+  return pkg.version;
+}
+
+// Published bin name is the agreed user-facing identifier for the preview.
+// We hard-code "prisma-cli" because the bin name and the npm package name differ:
+// the npm package is "@prisma/cli", but the binary on PATH is "prisma-cli".
+export function getCliName(): string {
+  return "prisma-cli";
+}
+
+export function detectInvocation(env: NodeJS.ProcessEnv, argv: readonly string[]): VersionInvocation {
+  if (env.npm_config_user_agent?.startsWith("bun")) {
+    return "bunx";
+  }
+
+  if (env.npm_lifecycle_event === "npx" || env.npm_execpath?.includes("/_npx/") || env.npm_config_user_agent?.startsWith("npm")) {
+    return "npx";
+  }
+
+  const entry = argv[1] ?? "";
+
+  if (entry.endsWith(".ts") || entry.includes("/tsx/")) {
+    return "dev";
+  }
+
+  if (entry.includes("/_npx/")) {
+    return "npx";
+  }
+
+  if (entry.includes("/.bun/")) {
+    return "bunx";
+  }
+
+  if (entry.includes("/node_modules/.bin/") || entry.endsWith("/prisma-cli")) {
+    return "global";
+  }
+
+  return "unknown";
+}
+
+export function buildVersionResult(env: NodeJS.ProcessEnv, argv: readonly string[]): VersionResult {
+  return {
+    cli: {
+      name: getCliName(),
+      version: getCliVersion(),
+    },
+    node: {
+      version: process.version,
+    },
+    os: {
+      platform: process.platform,
+      arch: process.arch,
+    },
+    invocation: detectInvocation(env, argv),
+  };
+}

packages/cli/src/presenters/version.ts

@@ -0,0 +1,24 @@
+import { renderShow } from "../output/patterns";
+import type { CommandDescriptor } from "../shell/command-meta";
+import type { CommandContext } from "../shell/runtime";
+import type { VersionResult } from "../types/version";
+
+export function renderVersionSuccess(
+  context: CommandContext,
+  descriptor: CommandDescriptor,
+  result: VersionResult,
+): string[] {
+  return renderShow(
+    {
+      title: "Showing CLI build and environment.",
+      descriptor,
+      fields: [
+        { key: result.cli.name, value: result.cli.version },
+        { key: "node", value: result.node.version },
+        { key: "os", value: `${result.os.platform} ${result.os.arch}` },
+        { key: "invocation", value: result.invocation, tone: result.invocation === "unknown" ? "dim" : "default" },
+      ],
+    },
+    context.ui,
+  );
+}

packages/cli/src/shell/command-meta.ts

@@ -20,6 +20,12 @@ const DESCRIPTORS: CommandDescriptor[] = [
     longDescription:
       "Deploy your app with isolated infrastructure for every branch",
   },
+  {
+    id: "version",
+    path: ["prisma", "version"],
+    description: "Show CLI build and environment",
+    examples: ["prisma-cli version", "prisma-cli version --json"],
+  },
   {
     id: "auth",
     path: ["prisma", "auth"],

packages/cli/src/shell/global-flags.ts

@@ -17,6 +17,7 @@ export const COMPACT_GLOBAL_OPTION_FLAGS = [
   "--trace",
   "--no-interactive",
   "-y, --yes",
+  "--version",
 ];
 
 export function addGlobalFlags(command: Command): Command {

packages/cli/src/types/version.ts

@@ -0,0 +1,20 @@
+export interface VersionResult {
+  cli: {
+    name: string;
+    version: string;
+  };
+  node: {
+    version: string;
+  };
+  os: {
+    platform: string;
+    arch: string;
+  };
+  invocation: VersionInvocation;
+}
+
+export type VersionInvocation = "bunx" | "npx" | "global" | "dev" | "unknown";
+
+export interface VersionFlagResult {
+  version: string;
+}