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

package/dist/shell/command-meta.js

@@ -4,17 +4,21 @@ 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: "version",
+		path: ["prisma", "version"],
+		description: "Show CLI build and environment",
+		examples: ["prisma-cli version", "prisma-cli version --json"]
 	},
 	{
 		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 +27,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 +37,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 +47,32 @@ 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 and inspect your Prisma projects",
+		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 my-app --framework 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: "git",
+		path: ["prisma", "git"],
+		description: "Manage Git repository connections for a project",
+		examples: ["prisma-cli git connect", "prisma-cli git disconnect"]
 	},
 	{
 		id: "project.list",
@@ -81,9 +81,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,20 +91,32 @@ 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 which project is active for this directory",
+		examples: ["prisma-cli project show", "prisma-cli project show --project proj_123 --json"]
 	},
 	{
-		id: "project.link",
+		id: "git.connect",
 		path: [
 			"prisma",
-			"project",
-			"link"
+			"git",
+			"connect"
 		],
-		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: "Connect the resolved project to a GitHub repository",
+		examples: [
+			"prisma-cli git connect",
+			"prisma-cli git connect git@github.com:prisma/prisma-cli.git",
+			"prisma-cli git connect --project proj_123"
+		]
+	},
+	{
+		id: "git.disconnect",
+		path: [
+			"prisma",
+			"git",
+			"disconnect"
+		],
+		description: "Disconnect the GitHub repository from the resolved project",
+		examples: ["prisma-cli git disconnect", "prisma-cli git disconnect --project proj_123"]
 	},
 	{
 		id: "branch.list",
@@ -114,9 +125,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 for the resolved project",
+		examples: ["prisma-cli branch list", "prisma-cli branch list --json"]
 	},
 	{
 		id: "branch.show",
@@ -125,9 +135,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 +146,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 +155,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 +169,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 +179,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 my-app --env DATABASE_URL=postgresql://example",
+			"prisma-cli app deploy --app my-app --framework nextjs --http-port 3000",
+			"prisma-cli app deploy --branch feat-login --framework hono"
 		]
 	},
 	{
@@ -190,8 +195,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 +205,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 +214,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 +224,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 +234,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 +244,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 +254,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 +264,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 +274,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 +284,70 @@ 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 active 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",
+			"API_URL=https://api.example prisma-cli project env add API_URL --project proj_123 --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,9 +1,15 @@
-import { CliError } from "./errors.js";
+import { CliError, authRequiredError } 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";
+import { AuthError } from "@prisma/management-api-sdk";
 //#region src/shell/command-runner.ts
+function toCliError(error) {
+	if (error instanceof CliError) return error;
+	if (error instanceof AuthError) return authRequiredError(["prisma-cli auth login"], { debug: error.message });
+	return null;
+}
 async function runCommand(runtime, commandName, options, handler, presenter) {
 	const flags = resolveGlobalFlags(runtime.argv, options);
 	const context = await createCommandContext(runtime, flags);
@@ -20,14 +26,46 @@ async function runCommand(runtime, commandName, options, handler, presenter) {
 		if (flags.quiet) return;
 		writeHumanLines(context.output, presenter.renderHuman(context, descriptor, success.result));
 	} catch (error) {
-		if (error instanceof CliError) {
-			if (flags.json) writeJsonError(context.output, commandName, error);
-			else writeHumanError(context.output, context.ui, error, { trace: flags.trace });
-			process.exitCode = error.exitCode;
+		const cliError = toCliError(error);
+		if (cliError) {
+			if (flags.json) writeJsonError(context.output, commandName, cliError);
+			else writeHumanError(context.output, context.ui, cliError, { trace: flags.trace });
+			process.exitCode = cliError.exitCode;
+			return;
+		}
+		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) {
+		const cliError = toCliError(error);
+		if (cliError) {
+			if (flags.json) writeJsonEvent(context.output, {
+				type: "error",
+				command: commandName,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				error: cliErrorToJson(cliError),
+				warnings: [],
+				nextSteps: cliError.nextSteps
+			});
+			else writeHumanError(context.output, context.ui, cliError, { trace: flags.trace });
+			process.exitCode = cliError.exitCode;
 			return;
 		}
 		throw error;
 	}
 }
 //#endregion
-export { runCommand };
+export { runCommand, runStreamingCommand };

package/dist/shell/errors.js

@@ -12,6 +12,7 @@ var CliError = class extends Error {
 	docsUrl;
 	exitCode;
 	nextSteps;
+	humanLines;
 	constructor(options) {
 		super(options.summary);
 		this.name = "CliError";
@@ -27,6 +28,7 @@ var CliError = class extends Error {
 		this.docsUrl = options.docsUrl ?? null;
 		this.exitCode = options.exitCode ?? 1;
 		this.nextSteps = options.nextSteps ?? [];
+		this.humanLines = options.humanLines && options.humanLines.length > 0 ? [...options.humanLines] : null;
 	}
 };
 function usageError(summary, why, fix, nextSteps = [], domain = "cli") {
@@ -40,17 +42,21 @@ function usageError(summary, why, fix, nextSteps = [], domain = "cli") {
 		nextSteps
 	});
 }
-function authRequiredError(nextSteps = ["prisma auth login"]) {
+function authRequiredError(nextSteps = ["prisma-cli auth login"], options = {}) {
 	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.",
+		debug: options.debug,
 		exitCode: 1,
 		nextSteps
 	});
 }
+function workspaceRequiredError() {
+	return usageError("Workspace required", "This command needs an active workspace, but the authenticated session does not have one.", "Run prisma-cli auth login and choose a workspace.", ["prisma-cli auth login"], "auth");
+}
 function featureUnavailableError(summary, why, fix, nextSteps = [], domain = "cli") {
 	return new CliError({
 		code: "FEATURE_UNAVAILABLE",
@@ -63,4 +69,4 @@ function featureUnavailableError(summary, why, fix, nextSteps = [], domain = "cl
 	});
 }
 //#endregion
-export { CliError, authRequiredError, featureUnavailableError, usageError };
+export { CliError, authRequiredError, featureUnavailableError, usageError, workspaceRequiredError };

package/dist/shell/global-flags.js

@@ -1,8 +1,20 @@
 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",
+	"--version"
+];
 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 +34,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)}`);

package/dist/shell/output.js

@@ -6,21 +6,27 @@ function writeJsonSuccess(output, success) {
 		...success
 	}, null, 2)}\n`);
 }
+function writeJsonEvent(output, event) {
+	output.stdout.write(`${JSON.stringify(event)}\n`);
+}
+function cliErrorToJson(error) {
+	return {
+		code: error.code,
+		domain: error.domain,
+		severity: error.severity,
+		summary: error.summary,
+		why: error.why,
+		fix: error.fix,
+		where: error.where,
+		meta: error.meta,
+		docsUrl: error.docsUrl
+	};
+}
 function writeJsonError(output, command, error) {
 	output.stdout.write(`${JSON.stringify({
 		ok: false,
 		command,
-		error: {
-			code: error.code,
-			domain: error.domain,
-			severity: error.severity,
-			summary: error.summary,
-			why: error.why,
-			fix: error.fix,
-			where: error.where,
-			meta: error.meta,
-			docsUrl: error.docsUrl
-		},
+		error: cliErrorToJson(error),
 		warnings: [],
 		nextSteps: error.nextSteps
 	}, null, 2)}\n`);
@@ -30,6 +36,17 @@ function writeHumanLines(output, lines) {
 	output.stderr.write(`${lines.join("\n")}\n`);
 }
 function writeHumanError(output, ui, error, options) {
+	if (error.humanLines && error.humanLines.length > 0) {
+		const lines = [...error.humanLines];
+		if (options.trace && error.debug) {
+			lines.push("");
+			lines.push("Trace:");
+			lines.push(...error.debug.trimEnd().split("\n"));
+		}
+		lines.push(...renderNextSteps(error.nextSteps));
+		writeHumanLines(output, lines);
+		return;
+	}
 	const lines = [renderSummaryLine(ui, "error", `${error.summary} [${error.code}]`)];
 	if (error.where) lines.push(...["", `Where: ${error.where}`]);
 	if (error.why) {
@@ -51,4 +68,4 @@ function writeHumanError(output, ui, error, options) {
 	writeHumanLines(output, lines);
 }
 //#endregion
-export { writeHumanError, writeHumanLines, writeJsonError, writeJsonSuccess };
+export { cliErrorToJson, writeHumanError, writeHumanLines, writeJsonError, writeJsonEvent, writeJsonSuccess };