@prisma/cli 3.0.0-alpha.1 → 3.0.0-alpha.3

package/dist/presenters/app-env.js

@@ -0,0 +1,129 @@
+import { renderList, renderShow, serializeList } from "../output/patterns.js";
+//#region src/presenters/app-env.ts
+function scopeLabel(scope) {
+	return scope.role;
+}
+function renderEnvAdd(context, descriptor, result) {
+	return renderShow({
+		title: "Setting a new environment variable.",
+		descriptor,
+		fields: [
+			{
+				key: "project",
+				value: result.projectId
+			},
+			{
+				key: "scope",
+				value: scopeLabel(result.scope)
+			},
+			{
+				key: "key",
+				value: result.variable.key
+			},
+			{
+				key: "id",
+				value: result.variable.id,
+				tone: "dim"
+			},
+			{
+				key: "last updated",
+				value: result.variable.updatedAt,
+				tone: "dim"
+			}
+		]
+	}, context.ui);
+}
+function serializeEnvAdd(result) {
+	return result;
+}
+function renderEnvUpdate(context, descriptor, result) {
+	return renderShow({
+		title: "Replacing the environment variable's value.",
+		descriptor,
+		fields: [
+			{
+				key: "project",
+				value: result.projectId
+			},
+			{
+				key: "scope",
+				value: scopeLabel(result.scope)
+			},
+			{
+				key: "key",
+				value: result.variable.key
+			},
+			{
+				key: "id",
+				value: result.variable.id,
+				tone: "dim"
+			},
+			{
+				key: "last updated",
+				value: result.variable.updatedAt,
+				tone: "dim"
+			}
+		]
+	}, context.ui);
+}
+function serializeEnvUpdate(result) {
+	return result;
+}
+function renderEnvList(context, descriptor, result) {
+	return renderList({
+		title: "Listing environment variables for the selected scope.",
+		descriptor,
+		parentContext: {
+			key: "scope",
+			value: scopeLabel(result.scope)
+		},
+		items: result.variables.map((variable) => ({
+			noun: "variable",
+			label: variable.key,
+			id: variable.id,
+			status: variable.isManagedBySystem ? "default" : null
+		})),
+		emptyMessage: "No environment variables defined in this scope."
+	}, context.ui);
+}
+function serializeEnvList(result) {
+	return {
+		projectId: result.projectId,
+		scope: result.scope,
+		...serializeList({
+			context: { scope: scopeLabel(result.scope) },
+			items: result.variables.map((variable) => ({
+				noun: "variable",
+				label: variable.key,
+				id: variable.id,
+				status: variable.isManagedBySystem ? "default" : null
+			}))
+		}),
+		variables: result.variables
+	};
+}
+function renderEnvRm(context, descriptor, result) {
+	return renderShow({
+		title: "Removing the environment variable from the scope.",
+		descriptor,
+		fields: [
+			{
+				key: "project",
+				value: result.projectId
+			},
+			{
+				key: "scope",
+				value: scopeLabel(result.scope)
+			},
+			{
+				key: "key",
+				value: result.key
+			}
+		]
+	}, context.ui);
+}
+function serializeEnvRm(result) {
+	return result;
+}
+//#endregion
+export { renderEnvAdd, renderEnvList, renderEnvRm, renderEnvUpdate, serializeEnvAdd, serializeEnvList, serializeEnvRm, serializeEnvUpdate };

package/dist/presenters/auth.js

@@ -9,7 +9,7 @@ function renderAuthSuccess(context, descriptor, command, result) {
 		});
 		if (result.user) rows.push({
 			key: "user",
-			value: `${result.user.name} <${result.user.email}>`
+			value: result.user.email
 		});
 		if (result.workspace?.name) rows.push({
 			key: "workspace",
@@ -47,7 +47,7 @@ function renderAuthSuccess(context, descriptor, command, result) {
 			},
 			...result.user ? [{
 				key: "user",
-				value: `${result.user.name} <${result.user.email}>`
+				value: result.user.email
 			}] : [],
 			...result.provider ? [{
 				key: "provider",

package/dist/shell/command-meta.js

@@ -4,17 +4,15 @@ const DESCRIPTORS = [
 	{
 		id: "root",
 		path: ["prisma"],
-		description: "Unified Prisma CLI.",
-		docsPath: "docs/product/command-principles.md",
-		examples: ["prisma auth login", "prisma project list"],
-		longDescription: "The Prisma CLI groups commands by developer workflow and keeps human and agent behavior aligned."
+		description: "The Prisma Developer Platform, from your terminal",
+		examples: ["prisma-cli auth login", "prisma-cli app deploy"],
+		longDescription: "Deploy your app with isolated infrastructure for every branch"
 	},
 	{
 		id: "auth",
 		path: ["prisma", "auth"],
-		description: "Authentication and identity commands.",
-		docsPath: "docs/product/command-spec.md#prisma-auth-login",
-		examples: ["prisma auth login", "prisma auth whoami"]
+		description: "Manage local authentication for the CLI",
+		examples: ["prisma-cli auth login", "prisma-cli auth whoami"]
 	},
 	{
 		id: "auth.login",
@@ -23,9 +21,8 @@ const DESCRIPTORS = [
 			"auth",
 			"login"
 		],
-		description: "Start an authenticated CLI session.",
-		docsPath: "docs/product/command-spec.md#prisma-auth-login",
-		examples: ["prisma auth login"]
+		description: "Log in to your Prisma platform account",
+		examples: ["prisma-cli auth login"]
 	},
 	{
 		id: "auth.logout",
@@ -34,9 +31,8 @@ const DESCRIPTORS = [
 			"auth",
 			"logout"
 		],
-		description: "Clear the current CLI session.",
-		docsPath: "docs/product/command-spec.md#prisma-auth-logout",
-		examples: ["prisma auth logout"]
+		description: "Clear stored authentication credentials",
+		examples: ["prisma-cli auth logout"]
 	},
 	{
 		id: "auth.whoami",
@@ -45,34 +41,26 @@ const DESCRIPTORS = [
 			"auth",
 			"whoami"
 		],
-		description: "Show the current authenticated identity.",
-		docsPath: "docs/product/command-spec.md#prisma-auth-whoami",
-		examples: ["prisma auth whoami", "prisma auth whoami --json"]
+		description: "Show the authenticated user and accessible workspace",
+		examples: ["prisma-cli auth whoami", "prisma-cli auth whoami --json"]
 	},
 	{
 		id: "project",
 		path: ["prisma", "project"],
-		description: "Project discovery and repo linking commands.",
-		docsPath: "docs/product/command-spec.md#prisma-project-list",
-		examples: ["prisma project list", "prisma project show"]
+		description: "Manage the link between this directory and a Prisma project",
+		examples: ["prisma-cli project list", "prisma-cli project show"]
 	},
 	{
 		id: "app",
 		path: ["prisma", "app"],
-		description: "App deployment and release commands.",
-		docsPath: "docs/product/command-spec.md#prisma-app-deploy---app-name---entry-path---build-type-autobunnextjsnuxtastrotanstack-start---http-port-port---env-namevalue",
-		examples: [
-			"prisma app build --build-type nextjs",
-			"prisma app deploy --app hello-world --build-type nextjs --http-port 3000",
-			"prisma app deploy --app hello-world --build-type nuxt"
-		]
+		description: "Manage apps and deployments for a project",
+		examples: ["prisma-cli app deploy", "prisma-cli app deploy --app hello-world --build-type nextjs --http-port 3000"]
 	},
 	{
 		id: "branch",
 		path: ["prisma", "branch"],
-		description: "Branch context and safety commands.",
-		docsPath: "docs/product/command-spec.md#prisma-branch-list",
-		examples: ["prisma branch list", "prisma branch use production"]
+		description: "View your active Platform branches",
+		examples: ["prisma-cli branch list", "prisma-cli branch show"]
 	},
 	{
 		id: "project.list",
@@ -81,9 +69,8 @@ const DESCRIPTORS = [
 			"project",
 			"list"
 		],
-		description: "List projects for the authenticated workspace.",
-		docsPath: "docs/product/command-spec.md#prisma-project-list",
-		examples: ["prisma project list", "prisma project list --json"]
+		description: "List all projects in your workspace",
+		examples: ["prisma-cli project list", "prisma-cli project list --json"]
 	},
 	{
 		id: "project.show",
@@ -92,9 +79,8 @@ const DESCRIPTORS = [
 			"project",
 			"show"
 		],
-		description: "Show the linked project for the current repo.",
-		docsPath: "docs/product/command-spec.md#prisma-project-show",
-		examples: ["prisma project show", "prisma project show --json"]
+		description: "Show the Prisma project linked to this directory",
+		examples: ["prisma-cli project show", "prisma-cli project show --json"]
 	},
 	{
 		id: "project.link",
@@ -103,9 +89,8 @@ const DESCRIPTORS = [
 			"project",
 			"link"
 		],
-		description: "Link the current repo to an existing project.",
-		docsPath: "docs/product/command-spec.md#prisma-project-link-project",
-		examples: ["prisma project link", "prisma project link proj_123"]
+		description: "Link this directory to a Prisma project",
+		examples: ["prisma-cli project link", "prisma-cli project link proj_123"]
 	},
 	{
 		id: "branch.list",
@@ -114,9 +99,8 @@ const DESCRIPTORS = [
 			"branch",
 			"list"
 		],
-		description: "List branches for the linked project.",
-		docsPath: "docs/product/command-spec.md#prisma-branch-list",
-		examples: ["prisma branch list", "prisma branch list --json"]
+		description: "List active Platform branches linked to this project",
+		examples: ["prisma-cli branch list", "prisma-cli branch list --json"]
 	},
 	{
 		id: "branch.show",
@@ -125,9 +109,8 @@ const DESCRIPTORS = [
 			"branch",
 			"show"
 		],
-		description: "Show the current active branch context.",
-		docsPath: "docs/product/command-spec.md#prisma-branch-show",
-		examples: ["prisma branch show", "prisma branch show --json"]
+		description: "Show the Platform branch matching your current Git branch",
+		examples: ["prisma-cli branch show", "prisma-cli branch show --json"]
 	},
 	{
 		id: "branch.use",
@@ -137,8 +120,7 @@ const DESCRIPTORS = [
 			"use"
 		],
 		description: "Change the local default branch context.",
-		docsPath: "docs/product/command-spec.md#prisma-branch-use-name",
-		examples: ["prisma branch use", "prisma branch use production"]
+		examples: ["prisma-cli branch use", "prisma-cli branch use production"]
 	},
 	{
 		id: "app.build",
@@ -147,12 +129,11 @@ const DESCRIPTORS = [
 			"app",
 			"build"
 		],
-		description: "Build the local app into a deployable artifact.",
-		docsPath: "docs/product/command-spec.md#prisma-app-build---entry-path---build-type-autobunnextjsnuxtastrotanstack-start",
+		description: "Build the app locally into a deployable artifact",
 		examples: [
-			"prisma app build --build-type nextjs",
-			"prisma app build --build-type nuxt",
-			"prisma app build --build-type bun --entry server.ts"
+			"prisma-cli app build --build-type nextjs",
+			"prisma-cli app build --build-type nuxt",
+			"prisma-cli app build --build-type bun --entry server.ts"
 		]
 	},
 	{
@@ -162,9 +143,8 @@ const DESCRIPTORS = [
 			"app",
 			"run"
 		],
-		description: "Start a local framework dev server.",
-		docsPath: "docs/product/command-spec.md#prisma-app-run---entry-path---build-type-autobunnextjs---port-port",
-		examples: ["prisma app run --build-type nextjs", "prisma app run --build-type bun --entry server.ts --port 3000"]
+		description: "Run your app locally",
+		examples: ["prisma-cli app run --build-type nextjs", "prisma-cli app run --build-type bun --entry server.ts --port 3000"]
 	},
 	{
 		id: "app.deploy",
@@ -173,13 +153,12 @@ const DESCRIPTORS = [
 			"app",
 			"deploy"
 		],
-		description: "Build and release the selected app.",
-		docsPath: "docs/product/command-spec.md#prisma-app-deploy---app-name---entry-path---build-type-autobunnextjsnuxtastrotanstack-start---http-port-port---env-namevalue",
+		description: "Creates a new deployment for the app",
 		examples: [
-			"prisma app deploy",
-			"prisma app deploy --app hello-world --env DATABASE_URL=postgresql://example",
-			"prisma app deploy --app hello-world --build-type nextjs --http-port 3000",
-			"prisma app deploy --app hello-world --build-type nuxt"
+			"prisma-cli app deploy",
+			"prisma-cli app deploy --app hello-world --env DATABASE_URL=postgresql://example",
+			"prisma-cli app deploy --app hello-world --build-type nextjs --http-port 3000",
+			"prisma-cli app deploy --app hello-world --build-type nuxt"
 		]
 	},
 	{
@@ -190,8 +169,7 @@ const DESCRIPTORS = [
 			"update-env"
 		],
 		description: "Create a new deployment with updated environment variables.",
-		docsPath: "docs/product/command-spec.md#prisma-app-update-env---app-name---env-namevalue",
-		examples: ["prisma app update-env --env DATABASE_URL=postgresql://example", "prisma app update-env --app hello-world --env DATABASE_URL=postgresql://another"]
+		examples: ["prisma-cli app update-env --env DATABASE_URL=postgresql://example", "prisma-cli app update-env --app hello-world --env DATABASE_URL=postgresql://another"]
 	},
 	{
 		id: "app.list-env",
@@ -201,8 +179,7 @@ const DESCRIPTORS = [
 			"list-env"
 		],
 		description: "List environment variable names for the selected app.",
-		docsPath: "docs/product/command-spec.md#prisma-app-list-env---app-name",
-		examples: ["prisma app list-env", "prisma app list-env --app hello-world"]
+		examples: ["prisma-cli app list-env", "prisma-cli app list-env --app hello-world"]
 	},
 	{
 		id: "app.show",
@@ -211,9 +188,8 @@ const DESCRIPTORS = [
 			"app",
 			"show"
 		],
-		description: "Show the current state of the selected app.",
-		docsPath: "docs/product/command-spec.md#prisma-app-show---app-name",
-		examples: ["prisma app show", "prisma app show --app hello-world"]
+		description: "Show the app and its current deployment",
+		examples: ["prisma-cli app show", "prisma-cli app show --app hello-world"]
 	},
 	{
 		id: "app.open",
@@ -222,9 +198,8 @@ const DESCRIPTORS = [
 			"app",
 			"open"
 		],
-		description: "Open the live URL for the selected app.",
-		docsPath: "docs/product/command-spec.md#prisma-app-open---app-name",
-		examples: ["prisma app open", "prisma app open --app hello-world"]
+		description: "Open the app's live URL",
+		examples: ["prisma-cli app open", "prisma-cli app open --app hello-world"]
 	},
 	{
 		id: "app.logs",
@@ -233,9 +208,8 @@ const DESCRIPTORS = [
 			"app",
 			"logs"
 		],
-		description: "Show or stream logs for a deployment.",
-		docsPath: "docs/product/command-spec.md#prisma-app-logs---app-name---deployment-id",
-		examples: ["prisma app logs", "prisma app logs --deployment dep_123"]
+		description: "Stream logs for the app's current deployment",
+		examples: ["prisma-cli app logs", "prisma-cli app logs --deployment dep_123"]
 	},
 	{
 		id: "app.list-deploys",
@@ -244,9 +218,8 @@ const DESCRIPTORS = [
 			"app",
 			"list-deploys"
 		],
-		description: "List deployments for the selected app.",
-		docsPath: "docs/product/command-spec.md#prisma-app-list-deploys---app-name",
-		examples: ["prisma app list-deploys", "prisma app list-deploys --app hello-world"]
+		description: "List deployments for the app",
+		examples: ["prisma-cli app list-deploys", "prisma-cli app list-deploys --app hello-world"]
 	},
 	{
 		id: "app.show-deploy",
@@ -255,9 +228,8 @@ const DESCRIPTORS = [
 			"app",
 			"show-deploy"
 		],
-		description: "Show one deployment in detail.",
-		docsPath: "docs/product/command-spec.md#prisma-app-show-deploy-deployment",
-		examples: ["prisma app show-deploy dep_123"]
+		description: "Show a deployment in detail",
+		examples: ["prisma-cli app show-deploy dep_123"]
 	},
 	{
 		id: "app.promote",
@@ -266,9 +238,8 @@ const DESCRIPTORS = [
 			"app",
 			"promote"
 		],
-		description: "Switch the live deployment for the selected app.",
-		docsPath: "docs/product/command-spec.md#prisma-app-promote-deployment---app-name",
-		examples: ["prisma app promote dep_123", "prisma app promote dep_123 --app hello-world"]
+		description: "Promote a deployment to production by rebuilding with production env vars",
+		examples: ["prisma-cli app promote dep_123", "prisma-cli app promote dep_123 --app hello-world"]
 	},
 	{
 		id: "app.rollback",
@@ -277,9 +248,8 @@ const DESCRIPTORS = [
 			"app",
 			"rollback"
 		],
-		description: "Restore the selected app to an earlier deployment.",
-		docsPath: "docs/product/command-spec.md#prisma-app-rollback---app-name---to-deployment",
-		examples: ["prisma app rollback", "prisma app rollback --app hello-world --to dep_123"]
+		description: "Roll back production to a previous deployment",
+		examples: ["prisma-cli app rollback", "prisma-cli app rollback --app hello-world --to dep_123"]
 	},
 	{
 		id: "app.remove",
@@ -288,9 +258,66 @@ const DESCRIPTORS = [
 			"app",
 			"remove"
 		],
-		description: "Remove the selected app from the linked project.",
-		docsPath: "docs/product/command-spec.md#prisma-app-remove---app-name--y---yes",
-		examples: ["prisma app remove --app hello-world", "prisma app remove --app hello-world --yes"]
+		description: "Remove the app from the current branch",
+		examples: ["prisma-cli app remove --app hello-world", "prisma-cli app remove --app hello-world --yes"]
+	},
+	{
+		id: "project.env",
+		path: [
+			"prisma",
+			"project",
+			"env"
+		],
+		description: "Manage environment variables for the linked project.",
+		examples: [
+			"prisma-cli project env list --role production",
+			"prisma-cli project env add STRIPE_KEY=sk_test_xxx --role production",
+			"prisma-cli project env rm STRIPE_KEY --role preview"
+		]
+	},
+	{
+		id: "project.env.add",
+		path: [
+			"prisma",
+			"project",
+			"env",
+			"add"
+		],
+		description: "Create a new environment variable.",
+		examples: ["prisma-cli project env add STRIPE_KEY=sk_test_xxx --role production", "prisma-cli project env add STRIPE_KEY=sk_test_xxx --role preview"]
+	},
+	{
+		id: "project.env.update",
+		path: [
+			"prisma",
+			"project",
+			"env",
+			"update"
+		],
+		description: "Replace an existing environment variable's value.",
+		examples: ["prisma-cli project env update STRIPE_KEY=sk_new_xxx --role production", "prisma-cli project env update STRIPE_KEY=sk_new_xxx --role preview"]
+	},
+	{
+		id: "project.env.list",
+		path: [
+			"prisma",
+			"project",
+			"env",
+			"list"
+		],
+		description: "List environment variable metadata for a scope (no values).",
+		examples: ["prisma-cli project env list --role production", "prisma-cli project env list --role preview"]
+	},
+	{
+		id: "project.env.rm",
+		path: [
+			"prisma",
+			"project",
+			"env",
+			"rm"
+		],
+		description: "Remove an environment variable from a scope.",
+		examples: ["prisma-cli project env rm STRIPE_KEY --role production", "prisma-cli project env rm STRIPE_KEY --role preview"]
 	}
 ];
 const DESCRIPTORS_BY_ID = new Map(DESCRIPTORS.map((descriptor) => [descriptor.id, descriptor]));

package/dist/shell/command-runner.js

@@ -1,8 +1,8 @@
 import { CliError } from "./errors.js";
+import { cliErrorToJson, writeHumanError, writeHumanLines, writeJsonError, writeJsonEvent, writeJsonSuccess } from "./output.js";
 import { getCommandDescriptor } from "./command-meta.js";
 import { resolveGlobalFlags } from "./global-flags.js";
 import { createCommandContext } from "./runtime.js";
-import { writeHumanError, writeHumanLines, writeJsonError, writeJsonSuccess } from "./output.js";
 //#region src/shell/command-runner.ts
 async function runCommand(runtime, commandName, options, handler, presenter) {
 	const flags = resolveGlobalFlags(runtime.argv, options);
@@ -29,5 +29,35 @@ async function runCommand(runtime, commandName, options, handler, presenter) {
 		throw error;
 	}
 }
+async function runStreamingCommand(runtime, commandName, options, handler) {
+	const flags = resolveGlobalFlags(runtime.argv, options);
+	const context = await createCommandContext(runtime, flags);
+	try {
+		await handler(context);
+		if (flags.json) writeJsonEvent(context.output, {
+			type: "success",
+			command: commandName,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			result: null,
+			warnings: [],
+			nextSteps: []
+		});
+	} catch (error) {
+		if (error instanceof CliError) {
+			if (flags.json) writeJsonEvent(context.output, {
+				type: "error",
+				command: commandName,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				error: cliErrorToJson(error),
+				warnings: [],
+				nextSteps: error.nextSteps
+			});
+			else writeHumanError(context.output, context.ui, error, { trace: flags.trace });
+			process.exitCode = error.exitCode;
+			return;
+		}
+		throw error;
+	}
+}
 //#endregion
-export { runCommand };
+export { runCommand, runStreamingCommand };

package/dist/shell/errors.js

@@ -40,13 +40,13 @@ function usageError(summary, why, fix, nextSteps = [], domain = "cli") {
 		nextSteps
 	});
 }
-function authRequiredError(nextSteps = ["prisma auth login"]) {
+function authRequiredError(nextSteps = ["prisma-cli auth login"]) {
 	return new CliError({
 		code: "AUTH_REQUIRED",
 		domain: "auth",
 		summary: "Authentication required",
 		why: "This command needs an authenticated session.",
-		fix: "Run prisma auth login, or rerun the command in a TTY to sign in interactively.",
+		fix: "Run prisma-cli auth login, or rerun the command in a TTY to sign in interactively.",
 		exitCode: 1,
 		nextSteps
 	});

package/dist/shell/global-flags.js

@@ -1,8 +1,19 @@
 import { Option } from "commander";
 //#region src/shell/global-flags.ts
+const COMPACT_GLOBAL_OPTION_FLAGS = [
+	"--json",
+	"-q, --quiet",
+	"-v, --verbose",
+	"--trace",
+	"--no-interactive",
+	"-y, --yes"
+];
 function addGlobalFlags(command) {
 	return command.option("--json", "Emit structured JSON output.").option("-q, --quiet", "Reduce human-oriented output.").option("-v, --verbose", "Increase human-oriented output detail.").option("--trace", "Show deeper diagnostics for failures.").option("-y, --yes", "Accept supported confirmation prompts.").addOption(new Option("--interactive", "Force interactive behavior when prompts are supported.")).addOption(new Option("--no-interactive", "Disable interactive behavior and prompts.")).addOption(new Option("--color", "Force color output in supported terminals.")).addOption(new Option("--no-color", "Disable color output."));
 }
+function addCompactGlobalFlags(command) {
+	return command.option("--json", "Emit structured JSON output.").option("-q, --quiet", "Reduce human-oriented output.").option("-v, --verbose", "Increase human-oriented output detail.").option("--trace", "Show deeper diagnostics for failures.").addOption(new Option("--no-interactive", "Disable interactive behavior and prompts.")).option("-y, --yes", "Accept supported confirmation prompts.");
+}
 function getExplicitBoolean(argv, positive, negative) {
 	for (let index = argv.length - 1; index >= 0; index -= 1) {
 		const value = argv[index];
@@ -22,4 +33,4 @@ function resolveGlobalFlags(argv, options) {
 	};
 }
 //#endregion
-export { addGlobalFlags, resolveGlobalFlags };
+export { COMPACT_GLOBAL_OPTION_FLAGS, addCompactGlobalFlags, addGlobalFlags, resolveGlobalFlags };

package/dist/shell/help.js

@@ -1,6 +1,6 @@
-import { formatDescriptorLabel, getDescriptorForCommand } from "./command-meta.js";
-import { resolveGlobalFlags } from "./global-flags.js";
 import { createShellUi, padDisplay, wrapText } from "./ui.js";
+import { formatDescriptorLabel, getDescriptorForCommand } from "./command-meta.js";
+import { COMPACT_GLOBAL_OPTION_FLAGS, resolveGlobalFlags } from "./global-flags.js";
 //#region src/shell/help.ts
 function renderHelp(command, runtime) {
 	const descriptor = getDescriptorForCommand(command);
@@ -10,8 +10,14 @@ function renderHelp(command, runtime) {
 	const visibleCommands = command.commands.filter((candidate) => candidate.name() !== "help" && !candidate.hidden);
 	const visibleOptions = command.options.filter((candidate) => !candidate.hidden);
 	if (visibleCommands.length > 0) lines.push(...renderCommandRows(rail, ui, visibleCommands));
+	if (descriptor.longDescription) {
+		lines.push(`${rail}`);
+		const wrapped = wrapText(descriptor.longDescription, Math.max(ui.width - 3, 40));
+		for (const line of wrapped) lines.push(`${rail}  ${line}`);
+	}
 	if (visibleOptions.length > 0) {
 		if (visibleCommands.length > 0) lines.push(`${rail}`);
+		if (visibleCommands.length > 0 && visibleOptions.every((option) => COMPACT_GLOBAL_OPTION_FLAGS.includes(option.flags))) lines.push(`${rail}  Global options:`);
 		lines.push(...renderOptionRows(rail, ui, visibleOptions));
 	}
 	if (descriptor.examples && descriptor.examples.length > 0) {
@@ -19,11 +25,6 @@ function renderHelp(command, runtime) {
 		lines.push(`${rail}  Examples:`);
 		for (const example of descriptor.examples) lines.push(`${rail}    $ ${example}`);
 	}
-	if (descriptor.longDescription) {
-		lines.push(`${rail}`);
-		const wrapped = wrapText(descriptor.longDescription, Math.max(ui.width - 3, 40));
-		for (const line of wrapped) lines.push(`${rail}  ${line}`);
-	}
 	if (descriptor.docsPath) {
 		lines.push(`${rail}`);
 		lines.push(`${rail}  ${ui.accent(padDisplay("Read more", 16))}  ${ui.link(descriptor.docsPath)}`);