@prisma/cli 3.0.0-beta.2 → 3.0.0-beta.20

package/dist/shell/command-meta.js

@@ -1,5 +1,11 @@
+import { resolvePrismaCliPackageCommandFormatterSync } from "../lib/agent/cli-command.js";
+import { PRISMA_AGENT_INSTALL_ARGS, PRISMA_AGENT_STATUS_ARGS, PRISMA_AGENT_UPDATE_ARGS, PRISMA_COMPUTE_AGENT_SKILL } from "../lib/agent/constants.js";
 //#region src/shell/command-meta.ts
 const COMMAND_DESCRIPTOR_ID = Symbol("prisma.commandDescriptorId");
+function agentCommandExamples(runtime, commands) {
+	const formatCommand = resolvePrismaCliPackageCommandFormatterSync(runtime.cwd);
+	return commands.map((command) => formatCommand(command));
+}
 const DESCRIPTORS = [
 	{
 		id: "root",
@@ -14,6 +20,71 @@ const DESCRIPTORS = [
 		description: "Show CLI build and environment",
 		examples: ["prisma-cli version", "prisma-cli version --json"]
 	},
+	{
+		id: "agent",
+		path: ["prisma", "agent"],
+		description: "Install Prisma context for AI coding agents",
+		examples: (runtime) => agentCommandExamples(runtime, [
+			PRISMA_AGENT_INSTALL_ARGS,
+			PRISMA_AGENT_UPDATE_ARGS,
+			PRISMA_AGENT_STATUS_ARGS
+		])
+	},
+	{
+		id: "agent.install",
+		path: [
+			"prisma",
+			"agent",
+			"install"
+		],
+		description: "Install Prisma skills for AI coding agents",
+		examples: (runtime) => agentCommandExamples(runtime, [
+			PRISMA_AGENT_INSTALL_ARGS,
+			[
+				...PRISMA_AGENT_INSTALL_ARGS,
+				"--agent",
+				"codex"
+			],
+			[...PRISMA_AGENT_INSTALL_ARGS, "--all-agents"],
+			[
+				...PRISMA_AGENT_INSTALL_ARGS,
+				"--skill",
+				PRISMA_COMPUTE_AGENT_SKILL
+			]
+		])
+	},
+	{
+		id: "agent.update",
+		path: [
+			"prisma",
+			"agent",
+			"update"
+		],
+		description: "Refresh Prisma skills for AI coding agents",
+		examples: (runtime) => agentCommandExamples(runtime, [
+			PRISMA_AGENT_UPDATE_ARGS,
+			[
+				...PRISMA_AGENT_UPDATE_ARGS,
+				"--agent",
+				"codex"
+			],
+			[...PRISMA_AGENT_UPDATE_ARGS, "--all-agents"]
+		])
+	},
+	{
+		id: "agent.status",
+		path: [
+			"prisma",
+			"agent",
+			"status"
+		],
+		description: "Show installed Prisma skills",
+		examples: (runtime) => agentCommandExamples(runtime, [
+			PRISMA_AGENT_STATUS_ARGS,
+			[...PRISMA_AGENT_STATUS_ARGS, "--json"],
+			[...PRISMA_AGENT_STATUS_ARGS, "--global"]
+		])
+	},
 	{
 		id: "auth",
 		path: ["prisma", "auth"],
@@ -50,6 +121,58 @@ const DESCRIPTORS = [
 		description: "Show the authenticated user and accessible workspace",
 		examples: ["prisma-cli auth whoami", "prisma-cli auth whoami --json"]
 	},
+	{
+		id: "auth.workspace",
+		path: [
+			"prisma",
+			"auth",
+			"workspace"
+		],
+		description: "Manage local authenticated workspaces",
+		examples: [
+			"prisma-cli auth workspace list",
+			"prisma-cli auth workspace use",
+			"prisma-cli auth workspace use wksp_123",
+			"prisma-cli auth workspace logout wksp_123"
+		]
+	},
+	{
+		id: "auth.workspace.list",
+		path: [
+			"prisma",
+			"auth",
+			"workspace",
+			"list"
+		],
+		description: "List locally authenticated workspaces",
+		examples: ["prisma-cli auth workspace list", "prisma-cli auth workspace list --json"]
+	},
+	{
+		id: "auth.workspace.use",
+		path: [
+			"prisma",
+			"auth",
+			"workspace",
+			"use"
+		],
+		description: "Switch the local CLI workspace",
+		examples: [
+			"prisma-cli auth workspace use",
+			"prisma-cli auth workspace use wksp_123",
+			"prisma-cli auth workspace use \"Acme Inc\""
+		]
+	},
+	{
+		id: "auth.workspace.logout",
+		path: [
+			"prisma",
+			"auth",
+			"workspace",
+			"logout"
+		],
+		description: "Remove one local OAuth workspace session",
+		examples: ["prisma-cli auth workspace logout wksp_123", "prisma-cli auth workspace logout \"Acme Inc\""]
+	},
 	{
 		id: "project",
 		path: ["prisma", "project"],
@@ -69,8 +192,34 @@ const DESCRIPTORS = [
 	{
 		id: "branch",
 		path: ["prisma", "branch"],
-		description: "View your active Platform branches",
-		examples: ["prisma-cli branch list", "prisma-cli branch show"]
+		description: "View your Platform branches",
+		examples: ["prisma-cli branch list"]
+	},
+	{
+		id: "build",
+		path: ["prisma", "build"],
+		description: "Inspect builds",
+		examples: ["prisma-cli build logs <build_id>"]
+	},
+	{
+		id: "build.logs",
+		path: [
+			"prisma",
+			"build",
+			"logs"
+		],
+		description: "Stream the logs for a build",
+		examples: ["prisma-cli build logs <build_id>", "prisma-cli build logs <build_id> --follow"]
+	},
+	{
+		id: "database",
+		path: ["prisma", "database"],
+		description: "Manage Prisma Postgres databases for a project",
+		examples: [
+			"prisma-cli database list",
+			"prisma-cli database create my-db",
+			"prisma-cli database connection create db_123"
+		]
 	},
 	{
 		id: "git",
@@ -153,28 +302,99 @@ const DESCRIPTORS = [
 			"branch",
 			"list"
 		],
-		description: "List active Platform branches for the resolved project",
+		description: "List Platform branches for the resolved project",
 		examples: ["prisma-cli branch list", "prisma-cli branch list --json"]
 	},
 	{
-		id: "branch.show",
+		id: "database.list",
 		path: [
 			"prisma",
-			"branch",
+			"database",
+			"list"
+		],
+		description: "List Prisma Postgres databases for the resolved project",
+		examples: [
+			"prisma-cli database list",
+			"prisma-cli database list --branch feature/foo",
+			"prisma-cli database list --json"
+		]
+	},
+	{
+		id: "database.show",
+		path: [
+			"prisma",
+			"database",
 			"show"
 		],
-		description: "Show the Platform branch matching your current Git branch",
-		examples: ["prisma-cli branch show", "prisma-cli branch show --json"]
+		description: "Show database metadata without secret values",
+		examples: ["prisma-cli database show db_123", "prisma-cli database show acme-preview --branch preview --json"]
 	},
 	{
-		id: "branch.use",
+		id: "database.create",
 		path: [
 			"prisma",
-			"branch",
-			"use"
+			"database",
+			"create"
+		],
+		description: "Create a Prisma Postgres database and print its one-time connection URL",
+		examples: ["prisma-cli database create my-db", "prisma-cli database create my-db --branch feature/foo --region eu-central-1"]
+	},
+	{
+		id: "database.remove",
+		path: [
+			"prisma",
+			"database",
+			"remove"
 		],
-		description: "Change the local default branch context.",
-		examples: ["prisma-cli branch use", "prisma-cli branch use production"]
+		description: "Remove a database after exact id confirmation",
+		examples: ["prisma-cli database remove db_123 --confirm db_123"]
+	},
+	{
+		id: "database.connection",
+		path: [
+			"prisma",
+			"database",
+			"connection"
+		],
+		description: "Manage one-time-view database connection strings",
+		examples: [
+			"prisma-cli database connection list db_123",
+			"prisma-cli database connection create db_123",
+			"prisma-cli database connection remove conn_123 --confirm conn_123"
+		]
+	},
+	{
+		id: "database.connection.list",
+		path: [
+			"prisma",
+			"database",
+			"connection",
+			"list"
+		],
+		description: "List database connection metadata without secret values",
+		examples: ["prisma-cli database connection list db_123", "prisma-cli database connection list acme-preview --branch preview --json"]
+	},
+	{
+		id: "database.connection.create",
+		path: [
+			"prisma",
+			"database",
+			"connection",
+			"create"
+		],
+		description: "Create a database connection and print its one-time connection URL",
+		examples: ["prisma-cli database connection create db_123", "prisma-cli database connection create db_123 --name readonly"]
+	},
+	{
+		id: "database.connection.remove",
+		path: [
+			"prisma",
+			"database",
+			"connection",
+			"remove"
+		],
+		description: "Remove a database connection after exact id confirmation",
+		examples: ["prisma-cli database connection remove conn_123 --confirm conn_123"]
 	},
 	{
 		id: "app.build",
@@ -208,15 +428,18 @@ const DESCRIPTORS = [
 			"deploy"
 		],
 		description: "Creates a new deployment for the app",
-		longDescription: "Agent skills for guided Next.js deploys are available from the Prisma CLI skill cluster.",
 		examples: [
 			"prisma-cli app deploy",
 			"prisma-cli app deploy --project proj_123",
 			"prisma-cli app deploy --create-project my-app --yes",
 			"prisma-cli app deploy --app my-app --env DATABASE_URL=postgresql://example",
+			"prisma-cli app deploy --env .env",
+			"prisma-cli app deploy --db",
+			"prisma-cli app deploy --db --yes",
 			"prisma-cli app deploy --app my-app --framework nextjs --http-port 3000",
+			"prisma-cli app deploy --app my-app --region us-west-1",
 			"prisma-cli app deploy --branch feat-login --framework hono",
-			"pnpm dlx skills@latest add prisma/prisma-cli/skills#cli-v<cli-version> --all",
+			"prisma-cli app deploy --prod --yes",
 			"prisma-cli app deploy --framework bun --entry src/server.ts"
 		]
 	},
@@ -378,8 +601,9 @@ const DESCRIPTORS = [
 		],
 		description: "Manage environment variables for the active project",
 		examples: [
-			"prisma-cli project env list --role production",
+			"prisma-cli project env list",
 			"prisma-cli project env add STRIPE_KEY=sk_test_xxx --role production",
+			"prisma-cli project env add --file .env --role preview",
 			"prisma-cli project env add DATABASE_URL=postgresql://branch --branch feature/foo",
 			"prisma-cli project env remove STRIPE_KEY --role preview"
 		]
@@ -396,7 +620,9 @@ const DESCRIPTORS = [
 		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",
+			"prisma-cli project env add --file .env --role preview",
 			"prisma-cli project env add DATABASE_URL=postgresql://branch --branch feature/foo",
+			"prisma-cli project env add --file .env.local --branch feature/foo",
 			"API_URL=https://api.example prisma-cli project env add API_URL --project proj_123 --role preview"
 		]
 	},
@@ -412,6 +638,7 @@ const DESCRIPTORS = [
 		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",
+			"prisma-cli project env update --file .env --role production",
 			"prisma-cli project env update DATABASE_URL=postgresql://branch --branch feature/foo"
 		]
 	},
@@ -425,6 +652,7 @@ const DESCRIPTORS = [
 		],
 		description: "List environment variable metadata for a scope (no values).",
 		examples: [
+			"prisma-cli project env list",
 			"prisma-cli project env list --role production",
 			"prisma-cli project env list --role preview",
 			"prisma-cli project env list --branch feature/foo"

package/dist/shell/command-runner.js

@@ -1,47 +1,86 @@
-import { CliError, authRequiredError } from "./errors.js";
-import { cliErrorToJson, writeHumanError, writeHumanLines, writeJsonError, writeJsonEvent, writeJsonSuccess } from "./output.js";
+import { CliError, authConfigInvalidError, authRequiredError, commandCanceledError } from "./errors.js";
 import { getCommandDescriptor } from "./command-meta.js";
 import { resolveGlobalFlags } from "./global-flags.js";
 import { createCommandContext } from "./runtime.js";
+import { collectCommandDiagnostics } from "../lib/diagnostics.js";
+import { renderCommandDiagnostics } from "./diagnostics-output.js";
+import { cliErrorToJson, writeHumanError, writeHumanLines, writeJsonError, writeJsonEvent, writeJsonSuccess } from "./output.js";
 import { AuthError } from "@prisma/management-api-sdk";
 //#region src/shell/command-runner.ts
-function toCliError(error) {
+function toCliError(error, runtime) {
+	if (isCancellationError(error) || runtime.signal.aborted) return commandCanceledError();
 	if (error instanceof CliError) return error;
 	if (error instanceof AuthError) return authRequiredError(["prisma-cli auth login"], { debug: error.message });
+	if (error instanceof Error && error.message.startsWith("PRISMA_SERVICE_TOKEN is set but empty")) return authConfigInvalidError(error.message);
 	return null;
 }
+function isCancellationError(error) {
+	if (!(error instanceof Error)) return false;
+	return error.name === "AbortError" || error.name === "CancelledError";
+}
 async function runCommand(runtime, commandName, options, handler, presenter) {
-	const flags = resolveGlobalFlags(runtime.argv, options);
-	const context = await createCommandContext(runtime, flags);
+	const context = await createCommandContext(runtime, resolveGlobalFlags(runtime.argv, options));
 	const descriptor = getCommandDescriptor(commandName);
+	const startedAt = Date.now();
 	try {
-		const success = await handler(context);
-		if (flags.json) {
-			writeJsonSuccess(context.output, {
-				...success,
-				result: presenter.renderJson ? presenter.renderJson(success.result) : success.result
-			});
-			return;
-		}
-		if (flags.quiet) return;
-		writeHumanLines(context.output, presenter.renderHuman(context, descriptor, success.result));
+		await writeCommandSuccess(context, descriptor, await handler(context), presenter, Date.now() - startedAt);
 	} catch (error) {
-		const cliError = toCliError(error);
+		const cliError = toCliError(error, runtime);
 		if (cliError) {
-			if (flags.json) writeJsonError(context.output, commandName, cliError);
-			else writeHumanError(context.output, context.ui, cliError, { trace: flags.trace });
+			writeCommandError(context, commandName, cliError);
 			process.exitCode = cliError.exitCode;
 			return;
 		}
 		throw error;
 	}
 }
-async function runStreamingCommand(runtime, commandName, options, handler) {
+async function writeCommandSuccess(context, descriptor, success, presenter, durationMs) {
+	if (context.flags.json) {
+		writeJsonSuccess(context.output, {
+			...success,
+			result: presenter.renderJson ? presenter.renderJson(success.result) : success.result
+		});
+		return;
+	}
+	const stdout = presenter.renderStdout?.(context, descriptor, success.result) ?? [];
+	if (context.flags.quiet) {
+		writeStdoutLines(context, stdout);
+		return;
+	}
+	const rendered = presenter.renderHuman(context, descriptor, success.result);
+	const diagnostics = await renderBestEffortCommandDiagnostics(context, {
+		enabled: context.flags.verbose && rendered.length > 0,
+		durationMs
+	});
+	const humanLines = [...rendered, ...diagnostics];
+	if (stdout.length > 0 && humanLines.length > 0) humanLines.push("");
+	writeHumanLines(context.output, humanLines);
+	writeStdoutLines(context, stdout);
+}
+function writeCommandError(context, commandName, cliError) {
+	if (context.flags.json) {
+		writeJsonError(context.output, commandName, cliError);
+		return;
+	}
+	writeHumanError(context.output, context.ui, cliError, { trace: context.flags.trace });
+}
+function writeStdoutLines(context, lines) {
+	if (lines.length > 0) context.output.stdout.write(`${lines.join("\n")}\n`);
+}
+async function renderBestEffortCommandDiagnostics(context, options) {
+	if (!options.enabled) return [];
+	try {
+		return renderCommandDiagnostics(context, await collectCommandDiagnostics(context, { durationMs: options.durationMs }));
+	} catch {
+		return [];
+	}
+}
+async function runStreamingCommand(runtime, commandName, options, handler, streamOptions) {
 	const flags = resolveGlobalFlags(runtime.argv, options);
 	const context = await createCommandContext(runtime, flags);
 	try {
 		await handler(context);
-		if (flags.json) writeJsonEvent(context.output, {
+		if (flags.json && (streamOptions?.emitJsonSuccessEvent ?? true)) writeJsonEvent(context.output, {
 			type: "success",
 			command: commandName,
 			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -51,7 +90,7 @@ async function runStreamingCommand(runtime, commandName, options, handler) {
 			nextActions: []
 		});
 	} catch (error) {
-		const cliError = toCliError(error);
+		const cliError = toCliError(error, runtime);
 		if (cliError) {
 			if (flags.json) writeJsonEvent(context.output, {
 				type: "error",

package/dist/shell/diagnostics-output.js

@@ -0,0 +1,57 @@
+import { renderVerboseBlock } from "./ui.js";
+import { shortenHomePath } from "../lib/fs/home-path.js";
+//#region src/shell/diagnostics-output.ts
+function renderCommandDiagnostics(context, diagnostics, rows = [], options = {}) {
+	if (!diagnostics) return [];
+	const { env } = context.runtime;
+	const git = diagnostics.git;
+	return renderVerboseBlock(context.ui, [
+		...rows,
+		...diagnostics.durationMs === void 0 ? [] : [{
+			key: "duration",
+			value: formatDuration(diagnostics.durationMs)
+		}],
+		{
+			key: "cwd",
+			value: formatLocalPath(diagnostics.cwd, env)
+		},
+		{
+			key: "state file",
+			value: formatLocalPath(diagnostics.stateFilePath, env)
+		},
+		...git ? [
+			{
+				key: "git ref",
+				value: git.ref ?? "detached",
+				tone: git.ref ? "default" : "dim"
+			},
+			{
+				key: "git sha",
+				value: git.sha ?? "unknown",
+				tone: git.sha ? "default" : "dim"
+			},
+			{
+				key: "git dirty",
+				value: formatDirtyState(git.dirty),
+				tone: git.dirty ? "warning" : "dim"
+			}
+		] : [{
+			key: "git",
+			value: "not detected",
+			tone: "dim"
+		}]
+	], { title: options.title ?? "Local context" });
+}
+function formatLocalPath(value, env) {
+	return shortenHomePath(value, env);
+}
+function formatDirtyState(dirty) {
+	if (dirty === null) return "unknown";
+	return dirty ? "yes" : "no";
+}
+function formatDuration(durationMs) {
+	if (durationMs < 1e3) return `${durationMs}ms`;
+	return `${(durationMs / 1e3).toFixed(1)}s`;
+}
+//#endregion
+export { renderCommandDiagnostics };

package/dist/shell/errors.js

@@ -56,9 +56,69 @@ function authRequiredError(nextSteps = ["prisma-cli auth login"], options = {})
 		nextSteps
 	});
 }
+function authConfigInvalidError(message) {
+	return new CliError({
+		code: "AUTH_CONFIG_INVALID",
+		domain: "auth",
+		summary: "Authentication configuration is invalid",
+		why: message,
+		fix: "Provide a valid PRISMA_SERVICE_TOKEN value, or unset the variable to use local OAuth login.",
+		exitCode: 1,
+		nextSteps: ["prisma-cli auth login"]
+	});
+}
+function commandCanceledError() {
+	return new CliError({
+		code: "COMMAND_CANCELED",
+		domain: "cli",
+		summary: "Command canceled",
+		why: null,
+		fix: null,
+		exitCode: 130,
+		humanLines: ["Command canceled [COMMAND_CANCELED]"]
+	});
+}
 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 workspaceSwitchUnavailableError() {
+	return new CliError({
+		code: "WORKSPACE_SWITCH_UNAVAILABLE",
+		domain: "auth",
+		summary: "Workspace switching is unavailable",
+		why: "PRISMA_SERVICE_TOKEN is set, so authenticated commands use that token instead of local OAuth workspaces.",
+		fix: "Unset PRISMA_SERVICE_TOKEN to switch between local OAuth workspaces, or use a token for the workspace you want.",
+		exitCode: 1,
+		nextSteps: ["unset PRISMA_SERVICE_TOKEN", "prisma-cli auth workspace list"]
+	});
+}
+function workspaceNotAuthenticatedError(workspaceRef) {
+	return new CliError({
+		code: "WORKSPACE_NOT_AUTHENTICATED",
+		domain: "auth",
+		summary: "Workspace is not authenticated",
+		why: `No stored OAuth session matched "${workspaceRef}".`,
+		fix: "Run prisma-cli auth login and authorize that workspace, then switch to it.",
+		meta: { workspaceRef },
+		exitCode: 1,
+		nextSteps: ["prisma-cli auth workspace list", "prisma-cli auth login"]
+	});
+}
+function workspaceAmbiguousError(workspaceRef, matches) {
+	return new CliError({
+		code: "WORKSPACE_AMBIGUOUS",
+		domain: "auth",
+		summary: "Workspace name is ambiguous",
+		why: `Multiple authenticated workspaces matched "${workspaceRef}".`,
+		fix: "Run prisma-cli auth workspace list and switch by workspace id.",
+		meta: {
+			workspaceRef,
+			matches
+		},
+		exitCode: 2,
+		nextSteps: ["prisma-cli auth workspace list"]
+	});
+}
 function featureUnavailableError(summary, why, fix, nextSteps = [], domain = "cli") {
 	return new CliError({
 		code: "FEATURE_UNAVAILABLE",
@@ -71,4 +131,4 @@ function featureUnavailableError(summary, why, fix, nextSteps = [], domain = "cl
 	});
 }
 //#endregion
-export { CliError, authRequiredError, featureUnavailableError, usageError, workspaceRequiredError };
+export { CliError, authConfigInvalidError, authRequiredError, commandCanceledError, featureUnavailableError, usageError, workspaceAmbiguousError, workspaceNotAuthenticatedError, workspaceRequiredError, workspaceSwitchUnavailableError };

package/dist/shell/help.js

@@ -1,5 +1,5 @@
-import { createShellUi, padDisplay, wrapText } from "./ui.js";
 import { formatDescriptorLabel, getDescriptorForCommand } from "./command-meta.js";
+import { createShellUi, padDisplay, wrapText } from "./ui.js";
 import { COMPACT_GLOBAL_OPTION_FLAGS, resolveGlobalFlags } from "./global-flags.js";
 //#region src/shell/help.ts
 function renderHelp(command, runtime) {
@@ -10,28 +10,39 @@ 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) {
-		lines.push(`${rail}`);
-		lines.push(`${rail}  Examples:`);
-		for (const example of descriptor.examples) lines.push(`${rail}    $ ${example}`);
-	}
-	if (descriptor.docsPath) {
-		lines.push(`${rail}`);
-		lines.push(`${rail}  ${ui.accent(padDisplay("Read more", 16))}  ${ui.link(descriptor.docsPath)}`);
-	}
+	lines.push(...renderLongDescription(rail, ui, descriptor.longDescription));
+	lines.push(...renderVisibleOptions(rail, ui, visibleCommands, visibleOptions));
+	lines.push(...renderExamples(rail, runtime, descriptor.examples));
+	lines.push(...renderDocsPath(rail, ui, descriptor.docsPath));
 	lines.push("");
 	return `${lines.join("\n")}`;
 }
+function renderLongDescription(rail, ui, longDescription) {
+	if (!longDescription) return [];
+	return [`${rail}`, ...wrapText(longDescription, Math.max(ui.width - 3, 40)).map((line) => `${rail}  ${line}`)];
+}
+function renderVisibleOptions(rail, ui, visibleCommands, visibleOptions) {
+	if (visibleOptions.length === 0) return [];
+	const lines = visibleCommands.length > 0 ? [`${rail}`] : [];
+	if (shouldLabelGlobalOptions(visibleCommands, visibleOptions)) lines.push(`${rail}  Global options:`);
+	return [...lines, ...renderOptionRows(rail, ui, visibleOptions)];
+}
+function shouldLabelGlobalOptions(visibleCommands, visibleOptions) {
+	return visibleCommands.length > 0 && visibleOptions.every((option) => COMPACT_GLOBAL_OPTION_FLAGS.includes(option.flags));
+}
+function renderExamples(rail, runtime, examples) {
+	const resolvedExamples = typeof examples === "function" ? examples(runtime) : examples;
+	if (!resolvedExamples || resolvedExamples.length === 0) return [];
+	return [
+		`${rail}`,
+		`${rail}  Examples:`,
+		...resolvedExamples.map((example) => `${rail}    $ ${example}`)
+	];
+}
+function renderDocsPath(rail, ui, docsPath) {
+	if (!docsPath) return [];
+	return [`${rail}`, `${rail}  ${ui.accent(padDisplay("Read more", 16))}  ${ui.link(docsPath)}`];
+}
 function renderCommandRows(rail, ui, commands) {
 	return renderAlignedRows(rail, ui, commands.map((command) => {
 		const descriptor = getDescriptorForCommand(command);

package/dist/shell/output.js

@@ -23,6 +23,15 @@ function cliErrorToJson(error) {
 		docsUrl: error.docsUrl
 	};
 }
+function formatUnexpectedError(error, trace) {
+	const debug = error instanceof Error ? error.stack ?? error.message : String(error);
+	if (trace) return `${debug}\n`;
+	return [
+		`Unexpected CLI error: ${error instanceof Error && error.message ? error.message : String(error)}`,
+		"More: Re-run with --trace for deeper diagnostics",
+		""
+	].join("\n");
+}
 function writeJsonError(output, command, error) {
 	output.stdout.write(`${JSON.stringify({
 		ok: false,
@@ -70,4 +79,4 @@ function writeHumanError(output, ui, error, options) {
 	writeHumanLines(output, lines);
 }
 //#endregion
-export { cliErrorToJson, writeHumanError, writeHumanLines, writeJsonError, writeJsonEvent, writeJsonSuccess };
+export { cliErrorToJson, formatUnexpectedError, writeHumanError, writeHumanLines, writeJsonError, writeJsonEvent, writeJsonSuccess };