Merge pull request #16 from prisma/feat/pro-174-version-command

feat(commands): added --version flag + version subcommand

Author: kristof-siket

docs/product/command-spec.md

@@ -15,6 +15,12 @@ The preview package includes these command groups:
 - `branch`
 - `app`
 
+The preview package also includes one top-level utility command:
+
+- `version`
+
+`version` is intentionally outside the workflow groups: it reports CLI build and environment state, requires no auth, no project context, and no network, and is the canonical answer to "is this CLI installed and on the build I expect?"
+
 The Git repository connection slice uses the `git` group. It does not add a
 provider-specific `GitHub` group.
 
@@ -29,6 +35,7 @@ Out of scope for the current preview:
 ## Global Rules
 
 - Canonical shape is `prisma <group> <action>`.
+- `version` is the one top-level command outside that shape (see Scope above).
 - Every command supports `--json`.
 - Shared global flags are:
   - `--json`
@@ -40,6 +47,9 @@ Out of scope for the current preview:
   - `-y`, `--yes`
   - `--color`
   - `--no-color`
+- Universal utility flags also work at the program level:
+  - `--help` — prints help for the root program or the named command and exits 0.
+  - `--version` — prints the CLI version and exits 0. Honors `--json` for the structured envelope. No short alias (`-v` is reserved for `--verbose`; `-V` is avoided as a near-collision).
 - Long flags use kebab-case.
 - Boolean negation uses `--no-<flag>`.
 - `--json` and non-interactive mode must not block on prompts.
@@ -139,6 +149,78 @@ Rules:
 - `workspace` is the active workspace or `null`
 - signed-out state is an empty auth state, not an error
 
+## `prisma-cli version`
+
+Purpose:
+
+- report the installed CLI build and a small block of host environment metadata
+
+Behavior:
+
+- requires no auth, no project context, and no network
+- reads the package's own version from its bundled metadata
+- reports CLI name, CLI version, Node.js version, OS platform, OS architecture, and a best-effort `invocation` label (`bunx`, `npx`, `global`, `dev`, or `unknown`)
+- uses the `show` output pattern (see `output-conventions.md`)
+- fails only when the bundled CLI metadata cannot be read; this is treated as `VERSION_UNAVAILABLE` and is not expected in practice
+
+In `--json`, `result` uses this shape:
+
+```json
+{
+  "cli": {
+    "name": "prisma-cli",
+    "version": "3.0.0-alpha.3"
+  },
+  "node": {
+    "version": "v24.14.1"
+  },
+  "os": {
+    "platform": "darwin",
+    "arch": "arm64"
+  },
+  "invocation": "bunx"
+}
+```
+
+Rules:
+
+- `cli.name` is the published package's `bin` name (`prisma-cli` in the current preview).
+- `cli.version` is the published package version.
+- `node.version` mirrors `process.version` exactly, including the leading `v`.
+- `os.platform` and `os.arch` mirror `process.platform` and `process.arch`.
+- `invocation` is best-effort and falls back to `"unknown"` when no signal is conclusive.
+
+Examples:
+
+```bash
+prisma-cli version
+prisma-cli version --json
+```
+
+## `prisma-cli --version`
+
+Purpose:
+
+- universal smoke-test flag at the root of the program
+
+Behavior:
+
+- prints the CLI version and exits 0
+- requires no auth, no project context, and no network
+- works before any subcommand parsing — bare `prisma-cli --version` is sufficient
+- in human mode, prints a single line to stdout: `prisma-cli <version>`
+- in `--json` mode, emits the standard success envelope (see Command Result Envelopes) with `command: "version"` and `result.version: "<version>"`
+- `--version` is documented as a universal utility flag in Global Rules, not as a shared global flag (it is an early-exit utility, not a per-command modifier)
+
+Examples:
+
+```bash
+prisma-cli --version
+prisma-cli --version --json
+```
+
+`prisma-cli version` is the richer environment report; `prisma-cli --version` is the terse one-liner. Both report the same `cli.version`. Use the flag for quick checks, the subcommand for support tickets and bug reports.
+
 ## `prisma-cli auth login`
 
 Purpose:

docs/product/error-conventions.md

@@ -169,6 +169,7 @@ These codes are the minimum stable set for the MVP:
 - `BUILD_FAILED`
 - `RUN_FAILED`
 - `DEPLOY_FAILED`
+- `VERSION_UNAVAILABLE`
 
 Recommended meanings:
 
@@ -196,6 +197,7 @@ Recommended meanings:
 - `BUILD_FAILED`: build failed before a healthy deployment existed
 - `RUN_FAILED`: local framework run command could not be started or exited unsuccessfully
 - `DEPLOY_FAILED`: deployment or post-build health failed
+- `VERSION_UNAVAILABLE`: CLI could not read its own bundled package metadata to report a version (defensive; not expected in normal installs)
 
 ## Exit Codes
 

docs/product/output-conventions.md

@@ -62,6 +62,7 @@ Current MVP commands map to patterns like this:
 
 | Command | Pattern |
 | --- | --- |
+| `version` | `show` |
 | `auth login` | `mutate` |
 | `auth logout` | `mutate` |
 | `auth whoami` | `show` |

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 { createGitCommand } from "./commands/git";
 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(createProjectCommand(runtime));
   program.addCommand(createGitCommand(runtime));
@@ -62,6 +75,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;
@@ -71,7 +132,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: [],
+  };
+}