@optique/core 1.4.0-dev.2678 → 1.4.0-dev.2679

package/dist/doc.cjs

@@ -141,7 +141,8 @@ function cloneDocEntry(entry) {
 		...entry.envVars != null && { envVars: [...entry.envVars] },
 		...entry.description != null && { description: require_message.cloneMessage(entry.description) },
 		...entry.default != null && { default: require_message.cloneMessage(entry.default) },
-		...entry.choices != null && { choices: require_message.cloneMessage(entry.choices) }
+		...entry.choices != null && { choices: require_message.cloneMessage(entry.choices) },
+		...entry.showAliases != null && { showAliases: entry.showAliases }
 	};
 }
 /**
@@ -310,6 +311,14 @@ function formatDocPage(programName, page, options = {}) {
 	const choicesAmbient = options.theme?.annotationStyles?.choices ?? { dim: true };
 	const environmentAmbient = options.theme?.annotationStyles?.environment ?? { dim: true };
 	const environmentStyle = require_terminal_internal.styleCode(environmentAmbient);
+	const aliasesAmbient = options.theme?.annotationStyles?.aliases ?? { dim: true };
+	const aliasesStyle = require_terminal_internal.styleCode(aliasesAmbient);
+	const showAliasesByDefault = options.showAliases != null && options.showAliases !== false;
+	const aliasesContent = (entry) => {
+		if (entry.term.type !== "command") return [];
+		if (!(entry.showAliases ?? showAliasesByDefault)) return [];
+		return (entry.term.aliases ?? []).filter((alias) => alias !== "").flatMap((alias, i) => i === 0 ? [require_message.text(alias)] : [require_message.text(", "), require_message.text(alias)]);
+	};
 	const environmentPlacement = typeof options.showEnvironment === "object" ? options.showEnvironment.placement ?? "inline" : options.showEnvironment ? "inline" : void 0;
 	const showInlineEnvironment = environmentPlacement === "inline" || environmentPlacement === "both";
 	const environmentContent = (entry) => [...new Set(entry.envVars ?? [])].filter((name) => name !== "").flatMap((name, i) => i === 0 ? [require_message.envVar(name)] : [require_message.text(", "), require_message.envVar(name)]);
@@ -322,7 +331,7 @@ function formatDocPage(programName, page, options = {}) {
 				type: "label",
 				label: label$1,
 				kind
-			}, options.theme, options.colors, void 0, kind === "choices" ? choicesAmbient : void 0);
+			}, options.theme, options.colors, void 0, kind === "choices" ? choicesAmbient : kind === "aliases" ? aliasesAmbient : void 0);
 			labelCache.set(key, rendered);
 		}
 		return rendered;
@@ -336,7 +345,7 @@ function formatDocPage(programName, page, options = {}) {
 				type: "syntaxPunctuation",
 				punctuation: punctuation$1,
 				kind
-			}, options.theme, options.colors, void 0, kind.startsWith("default") ? defaultAmbient : kind.startsWith("choices") ? choicesAmbient : void 0);
+			}, options.theme, options.colors, void 0, kind.startsWith("default") ? defaultAmbient : kind.startsWith("choices") ? choicesAmbient : kind.startsWith("aliases") ? aliasesAmbient : void 0);
 			punctuationCache.set(key, rendered);
 		}
 		return rendered;
@@ -372,7 +381,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
-	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices) || showInlineEnvironment && hasContent(environmentContent(entry));
+	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices) || showInlineEnvironment && hasContent(environmentContent(entry)) || hasContent(aliasesContent(entry));
 	const annotations = /* @__PURE__ */ new Map();
 	const annotation = (kind) => {
 		const cached = annotations.get(kind);
@@ -382,6 +391,12 @@ function formatDocPage(programName, page, options = {}) {
 			annotations.set(kind, layout$1);
 			return layout$1;
 		}
+		if (kind === "aliases") {
+			const config$1 = typeof options.showAliases === "object" ? options.showAliases : {};
+			const layout$1 = require_text_layout.measureAnnotation(punctuation(config$1.prefix ?? " (", "aliasesPrefix") + label(config$1.label ?? "aliases: ", "aliases"), punctuation(config$1.suffix ?? ")", "aliasesSuffix"));
+			annotations.set(kind, layout$1);
+			return layout$1;
+		}
 		const config = kind === "default" ? options.showDefault : options.showChoices;
 		const prefix = punctuation(typeof config === "object" ? config.prefix ?? (kind === "default" ? " [" : " (") : kind === "default" ? " [" : " (", kind === "default" ? "defaultPrefix" : "choicesPrefix");
 		const suffix = punctuation(typeof config === "object" ? config.suffix ?? (kind === "default" ? "]" : ")") : kind === "default" ? "]" : ")", kind === "default" ? "defaultSuffix" : "choicesSuffix");
@@ -420,10 +435,11 @@ function formatDocPage(programName, page, options = {}) {
 		if (needsDescColumn) for (const kind of [
 			"default",
 			"choices",
-			"environment"
+			"environment",
+			"aliases"
 		]) {
-			const enabled = kind === "default" ? options.showDefault : kind === "choices" ? options.showChoices : showInlineEnvironment;
-			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(kind === "environment" ? environmentContent(entry) : entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
+			const enabled = kind === "default" ? options.showDefault : kind === "choices" ? options.showChoices : kind === "environment" ? showInlineEnvironment : true;
+			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(kind === "environment" ? environmentContent(entry) : kind === "aliases" ? aliasesContent(entry) : entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
 		}
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
@@ -550,6 +566,8 @@ function formatDocPage(programName, page, options = {}) {
 				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
 				cursor = suffix.cursor;
 			};
+			const aliases = aliasesContent(entry);
+			if (hasContent(aliases)) appendAnnotation(aliases, annotation("aliases"), aliasesStyle, aliasesAmbient, false);
 			if (options.showDefault && hasContent(entry.default)) appendAnnotation(entry.default, annotation("default"), defaultStyle, defaultAmbient, !options.colors);
 			if (options.showChoices && hasContent(entry.choices)) {
 				const maxItems = typeof options.showChoices === "object" ? options.showChoices.maxItems ?? 8 : 8;

package/dist/doc.d.cts

@@ -41,6 +41,15 @@ interface DocEntry {
    * @since 1.4.0
    */
   readonly envVars?: readonly string[];
+  /**
+   * Per-entry override for showing the aliases of a command term.  When
+   * `true`, the term's `aliases` are shown even if the formatter's
+   * `showAliases` option is off; when `false`, they are hidden even if it is
+   * on.  When omitted, the formatter's `showAliases` option decides.
+   * Ignored for entries whose term is not a command.
+   * @since 1.4.0
+   */
+  readonly showAliases?: boolean;
 }
 /**
  * A section in a document that groups related entries together.
@@ -261,6 +270,28 @@ interface ShowChoicesOptions {
    */
   readonly maxItems?: number;
 }
+/**
+ * Configuration for customizing how command aliases are displayed in help
+ * output.
+ * @since 1.4.0
+ */
+interface ShowAliasesOptions {
+  /**
+   * Text to display before the alias list.
+   * @default `" ("`
+   */
+  readonly prefix?: string;
+  /**
+   * Text to display after the alias list.
+   * @default `")"`
+   */
+  readonly suffix?: string;
+  /**
+   * Label text to display before the individual aliases.
+   * @default `"aliases: "`
+   */
+  readonly label?: string;
+}
 /**
  * Options for formatting a documentation page.
  */
@@ -365,6 +396,31 @@ interface DocPageFormatOptions {
    * ```
    */
   showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * Whether and how to display the aliases of commands in command lists.
+   *
+   * - `boolean`: When `true`, displays aliases using format
+   *   `(aliases: i, add)`
+   * - `ShowAliasesOptions`: Custom formatting with configurable prefix,
+   *   suffix, and label
+   *
+   * This is the fallback for entries that do not set
+   * {@link DocEntry.showAliases}; an entry's own setting always wins.
+   * Aliases are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 1.4.0
+   *
+   * @example
+   * ```typescript
+   * // Basic usage - shows "(aliases: i, add)"
+   * { showAliases: true }
+   *
+   * // Custom format - shows "[aka i, add]"
+   * { showAliases: { prefix: " [", suffix: "]", label: "aka " } }
+   * ```
+   */
+  showAliases?: boolean | ShowAliasesOptions;
   /**
    * A custom comparator function to control the order of sections in the
    * help output.  When provided, it is used instead of the default smart
@@ -429,4 +485,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };

package/dist/doc.d.ts

@@ -41,6 +41,15 @@ interface DocEntry {
    * @since 1.4.0
    */
   readonly envVars?: readonly string[];
+  /**
+   * Per-entry override for showing the aliases of a command term.  When
+   * `true`, the term's `aliases` are shown even if the formatter's
+   * `showAliases` option is off; when `false`, they are hidden even if it is
+   * on.  When omitted, the formatter's `showAliases` option decides.
+   * Ignored for entries whose term is not a command.
+   * @since 1.4.0
+   */
+  readonly showAliases?: boolean;
 }
 /**
  * A section in a document that groups related entries together.
@@ -261,6 +270,28 @@ interface ShowChoicesOptions {
    */
   readonly maxItems?: number;
 }
+/**
+ * Configuration for customizing how command aliases are displayed in help
+ * output.
+ * @since 1.4.0
+ */
+interface ShowAliasesOptions {
+  /**
+   * Text to display before the alias list.
+   * @default `" ("`
+   */
+  readonly prefix?: string;
+  /**
+   * Text to display after the alias list.
+   * @default `")"`
+   */
+  readonly suffix?: string;
+  /**
+   * Label text to display before the individual aliases.
+   * @default `"aliases: "`
+   */
+  readonly label?: string;
+}
 /**
  * Options for formatting a documentation page.
  */
@@ -365,6 +396,31 @@ interface DocPageFormatOptions {
    * ```
    */
   showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * Whether and how to display the aliases of commands in command lists.
+   *
+   * - `boolean`: When `true`, displays aliases using format
+   *   `(aliases: i, add)`
+   * - `ShowAliasesOptions`: Custom formatting with configurable prefix,
+   *   suffix, and label
+   *
+   * This is the fallback for entries that do not set
+   * {@link DocEntry.showAliases}; an entry's own setting always wins.
+   * Aliases are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 1.4.0
+   *
+   * @example
+   * ```typescript
+   * // Basic usage - shows "(aliases: i, add)"
+   * { showAliases: true }
+   *
+   * // Custom format - shows "[aka i, add]"
+   * { showAliases: { prefix: " [", suffix: "]", label: "aka " } }
+   * ```
+   */
+  showAliases?: boolean | ShowAliasesOptions;
   /**
    * A custom comparator function to control the order of sections in the
    * help output.  When provided, it is used instead of the default smart
@@ -429,4 +485,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };

package/dist/doc.js

@@ -141,7 +141,8 @@ function cloneDocEntry(entry) {
 		...entry.envVars != null && { envVars: [...entry.envVars] },
 		...entry.description != null && { description: cloneMessage(entry.description) },
 		...entry.default != null && { default: cloneMessage(entry.default) },
-		...entry.choices != null && { choices: cloneMessage(entry.choices) }
+		...entry.choices != null && { choices: cloneMessage(entry.choices) },
+		...entry.showAliases != null && { showAliases: entry.showAliases }
 	};
 }
 /**
@@ -310,6 +311,14 @@ function formatDocPage(programName, page, options = {}) {
 	const choicesAmbient = options.theme?.annotationStyles?.choices ?? { dim: true };
 	const environmentAmbient = options.theme?.annotationStyles?.environment ?? { dim: true };
 	const environmentStyle = styleCode(environmentAmbient);
+	const aliasesAmbient = options.theme?.annotationStyles?.aliases ?? { dim: true };
+	const aliasesStyle = styleCode(aliasesAmbient);
+	const showAliasesByDefault = options.showAliases != null && options.showAliases !== false;
+	const aliasesContent = (entry) => {
+		if (entry.term.type !== "command") return [];
+		if (!(entry.showAliases ?? showAliasesByDefault)) return [];
+		return (entry.term.aliases ?? []).filter((alias) => alias !== "").flatMap((alias, i) => i === 0 ? [text(alias)] : [text(", "), text(alias)]);
+	};
 	const environmentPlacement = typeof options.showEnvironment === "object" ? options.showEnvironment.placement ?? "inline" : options.showEnvironment ? "inline" : void 0;
 	const showInlineEnvironment = environmentPlacement === "inline" || environmentPlacement === "both";
 	const environmentContent = (entry) => [...new Set(entry.envVars ?? [])].filter((name) => name !== "").flatMap((name, i) => i === 0 ? [envVar(name)] : [text(", "), envVar(name)]);
@@ -322,7 +331,7 @@ function formatDocPage(programName, page, options = {}) {
 				type: "label",
 				label: label$1,
 				kind
-			}, options.theme, options.colors, void 0, kind === "choices" ? choicesAmbient : void 0);
+			}, options.theme, options.colors, void 0, kind === "choices" ? choicesAmbient : kind === "aliases" ? aliasesAmbient : void 0);
 			labelCache.set(key, rendered);
 		}
 		return rendered;
@@ -336,7 +345,7 @@ function formatDocPage(programName, page, options = {}) {
 				type: "syntaxPunctuation",
 				punctuation: punctuation$1,
 				kind
-			}, options.theme, options.colors, void 0, kind.startsWith("default") ? defaultAmbient : kind.startsWith("choices") ? choicesAmbient : void 0);
+			}, options.theme, options.colors, void 0, kind.startsWith("default") ? defaultAmbient : kind.startsWith("choices") ? choicesAmbient : kind.startsWith("aliases") ? aliasesAmbient : void 0);
 			punctuationCache.set(key, rendered);
 		}
 		return rendered;
@@ -372,7 +381,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
-	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices) || showInlineEnvironment && hasContent(environmentContent(entry));
+	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices) || showInlineEnvironment && hasContent(environmentContent(entry)) || hasContent(aliasesContent(entry));
 	const annotations = /* @__PURE__ */ new Map();
 	const annotation = (kind) => {
 		const cached = annotations.get(kind);
@@ -382,6 +391,12 @@ function formatDocPage(programName, page, options = {}) {
 			annotations.set(kind, layout$1);
 			return layout$1;
 		}
+		if (kind === "aliases") {
+			const config$1 = typeof options.showAliases === "object" ? options.showAliases : {};
+			const layout$1 = measureAnnotation(punctuation(config$1.prefix ?? " (", "aliasesPrefix") + label(config$1.label ?? "aliases: ", "aliases"), punctuation(config$1.suffix ?? ")", "aliasesSuffix"));
+			annotations.set(kind, layout$1);
+			return layout$1;
+		}
 		const config = kind === "default" ? options.showDefault : options.showChoices;
 		const prefix = punctuation(typeof config === "object" ? config.prefix ?? (kind === "default" ? " [" : " (") : kind === "default" ? " [" : " (", kind === "default" ? "defaultPrefix" : "choicesPrefix");
 		const suffix = punctuation(typeof config === "object" ? config.suffix ?? (kind === "default" ? "]" : ")") : kind === "default" ? "]" : ")", kind === "default" ? "defaultSuffix" : "choicesSuffix");
@@ -420,10 +435,11 @@ function formatDocPage(programName, page, options = {}) {
 		if (needsDescColumn) for (const kind of [
 			"default",
 			"choices",
-			"environment"
+			"environment",
+			"aliases"
 		]) {
-			const enabled = kind === "default" ? options.showDefault : kind === "choices" ? options.showChoices : showInlineEnvironment;
-			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(kind === "environment" ? environmentContent(entry) : entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
+			const enabled = kind === "default" ? options.showDefault : kind === "choices" ? options.showChoices : kind === "environment" ? showInlineEnvironment : true;
+			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(kind === "environment" ? environmentContent(entry) : kind === "aliases" ? aliasesContent(entry) : entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
 		}
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
@@ -550,6 +566,8 @@ function formatDocPage(programName, page, options = {}) {
 				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
 				cursor = suffix.cursor;
 			};
+			const aliases = aliasesContent(entry);
+			if (hasContent(aliases)) appendAnnotation(aliases, annotation("aliases"), aliasesStyle, aliasesAmbient, false);
 			if (options.showDefault && hasContent(entry.default)) appendAnnotation(entry.default, annotation("default"), defaultStyle, defaultAmbient, !options.colors);
 			if (options.showChoices && hasContent(entry.choices)) {
 				const maxItems = typeof options.showChoices === "object" ? options.showChoices.maxItems ?? 8 : 8;

package/dist/facade.cjs

@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -1033,6 +1033,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							termWidth,
 							showDefault,
 							showChoices,
+							showAliases,
 							showEnvironment,
 							sectionOrder,
 							showUsage
@@ -1111,6 +1112,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							termWidth,
 							showDefault,
 							showChoices,
+							showAliases,
 							showEnvironment,
 							sectionOrder,
 							showUsage
@@ -1311,16 +1313,20 @@ function collapseTopLevelCommandEntries(entries) {
 		const isTopLevel = entry.term.name === topLevelName;
 		if (existingIndex == null) {
 			commandIndexes.set(topLevelName, collapsed.length);
-			collapsed.push(isTopLevel ? entry : { term: {
+			collapsed.push(isTopLevel ? entry : { term: omitCommandAliases({
 				...entry.term,
 				name: topLevelName
-			} });
+			}) });
 			continue;
 		}
 		if (isTopLevel) collapsed[existingIndex] = entry;
 	}
 	return collapsed;
 }
+function omitCommandAliases(term) {
+	const { aliases: _aliases,...rest } = term;
+	return rest;
+}
 function getTopLevelCommandName(name) {
 	return name.split(" ", 1)[0] ?? name;
 }

package/dist/facade.d.cts

@@ -1,7 +1,7 @@
 import { Message, MessageFormatter } from "./message.cjs";
 import { TerminalTheme } from "./terminal.cjs";
 import { HiddenVisibility, OptionName, Usage } from "./usage.cjs";
-import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions } from "./doc.cjs";
+import { DocPage, DocSection, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
@@ -148,6 +148,22 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * Whether and how to display command aliases in command lists of help
+   * output.
+   *
+   * - `boolean`: When `true`, displays aliases using format
+   *   `(aliases: i, add)`
+   * - `ShowAliasesOptions`: Custom formatting with configurable prefix,
+   *   suffix, and label
+   *
+   * This is the fallback for commands that do not set their own
+   * `showAliases` option.  Usage lines always show canonical command names.
+   *
+   * @default `false`
+   * @since 1.4.0
+   */
+  readonly showAliases?: boolean | ShowAliasesOptions;
   /**
    * Displays declared environment bindings in help. `true` selects inline
    * annotations; an object can select a section or both. Names without visible

package/dist/facade.d.ts

@@ -1,7 +1,7 @@
 import { Message, MessageFormatter } from "./message.js";
 import { TerminalTheme } from "./terminal.js";
 import { HiddenVisibility, OptionName, Usage } from "./usage.js";
-import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions } from "./doc.js";
+import { DocPage, DocSection, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.js";
 import { ShellCompletion } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
@@ -148,6 +148,22 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * Whether and how to display command aliases in command lists of help
+   * output.
+   *
+   * - `boolean`: When `true`, displays aliases using format
+   *   `(aliases: i, add)`
+   * - `ShowAliasesOptions`: Custom formatting with configurable prefix,
+   *   suffix, and label
+   *
+   * This is the fallback for commands that do not set their own
+   * `showAliases` option.  Usage lines always show canonical command names.
+   *
+   * @default `false`
+   * @since 1.4.0
+   */
+  readonly showAliases?: boolean | ShowAliasesOptions;
   /**
    * Displays declared environment bindings in help. `true` selects inline
    * annotations; an object can select a section or both. Names without visible

package/dist/facade.js

@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -1033,6 +1033,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							termWidth,
 							showDefault,
 							showChoices,
+							showAliases,
 							showEnvironment,
 							sectionOrder,
 							showUsage
@@ -1111,6 +1112,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							termWidth,
 							showDefault,
 							showChoices,
+							showAliases,
 							showEnvironment,
 							sectionOrder,
 							showUsage
@@ -1311,16 +1313,20 @@ function collapseTopLevelCommandEntries(entries) {
 		const isTopLevel = entry.term.name === topLevelName;
 		if (existingIndex == null) {
 			commandIndexes.set(topLevelName, collapsed.length);
-			collapsed.push(isTopLevel ? entry : { term: {
+			collapsed.push(isTopLevel ? entry : { term: omitCommandAliases({
 				...entry.term,
 				name: topLevelName
-			} });
+			}) });
 			continue;
 		}
 		if (isTopLevel) collapsed[existingIndex] = entry;
 	}
 	return collapsed;
 }
+function omitCommandAliases(term) {
+	const { aliases: _aliases,...rest } = term;
+	return rest;
+}
 function getTopLevelCommandName(name) {
 	return name.split(" ", 1)[0] ?? name;
 }

package/dist/index.d.cts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.cjs";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeInput, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeInput, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.js";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeInput, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeInput, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/primitives.cjs

@@ -1429,6 +1429,12 @@ function getVisibleCommandAliases(options) {
 	if (!isNonEmptyStringArray(aliases)) throw new TypeError("Command aliases must be a non-empty array of strings.");
 	return aliases;
 }
+function getShowCommandAliases(options) {
+	const showAliases = options.showAliases;
+	if (showAliases == null) return void 0;
+	if (typeof showAliases !== "boolean") throw new TypeError("Command showAliases must be a boolean.");
+	return showAliases;
+}
 function getHiddenCommandAliases(options) {
 	const hiddenAliases = options[require_command_alias.hiddenCommandAliasesKey];
 	if (hiddenAliases == null) return [];
@@ -1493,10 +1499,12 @@ async function* suggestCommandAsync(context, prefix, name, aliases, parser, opti
 *          to the inner parser for the remaining arguments.
 * @throws {TypeError} If `name` is empty, whitespace-only, contains
 *         embedded whitespace, or contains control characters.
+* @throws {TypeError} If `options.showAliases` is present but not a boolean.
 */
 function command(name, parser, options = {}) {
 	const commandNames = getCommandNames(name, options);
 	const aliases = getVisibleCommandAliases(options);
+	const showAliases = getShowCommandAliases(options);
 	const hiddenAliases = getHiddenCommandAliases(options);
 	require_validate.validateCommandNames(commandNames, "Command");
 	validateUniqueCommandNames(commandNames);
@@ -1697,9 +1705,11 @@ function command(name, parser, options = {}) {
 						type: "entry",
 						term: {
 							type: "command",
-							name
+							name,
+							...aliases.length > 0 && { aliases }
 						},
-						description: options.brief ?? options.description
+						description: options.brief ?? options.description,
+						...showAliases != null && { showAliases }
 					}]
 				};
 			}

package/dist/primitives.d.cts

@@ -465,13 +465,28 @@ interface CommandOptions {
   /**
    * Additional names that invoke this command.
    *
-   * Aliases are functional at runtime and are suggested by shell completion,
-   * but are hidden from usage and documentation output.  The `name` parameter
-   * passed to {@link command} remains the canonical display name.
+   * Aliases are functional at runtime and are suggested by shell completion.
+   * By default they are hidden from usage and documentation output; set
+   * {@link showAliases} or the help formatter's `showAliases` option to list
+   * them next to the command in command lists.  Usage lines always show
+   * only the `name` parameter passed to {@link command}, which remains the
+   * canonical display name.
    *
    * @since 1.1.0
    */
   readonly aliases?: readonly [string, ...string[]];
+  /**
+   * Whether to show {@link aliases} next to this command in command lists
+   * of help and documentation output, e.g., `(aliases: i, add)`.
+   *
+   * When omitted, the help formatter's `showAliases` option decides, which
+   * defaults to hiding aliases.  `true` shows them and `false` hides them
+   * regardless of that option.  This setting does not affect usage lines
+   * and does not apply to nested subcommands.
+   *
+   * @since 1.4.0
+   */
+  readonly showAliases?: boolean;
   /**
    * Error messages customization.
    * @since 0.5.0
@@ -522,6 +537,7 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  *          to the inner parser for the remaining arguments.
  * @throws {TypeError} If `name` is empty, whitespace-only, contains
  *         embedded whitespace, or contains control characters.
+ * @throws {TypeError} If `options.showAliases` is present but not a boolean.
  */
 declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): FluentParser<M, T, CommandState<TState>>;
 /**

package/dist/primitives.d.ts

@@ -465,13 +465,28 @@ interface CommandOptions {
   /**
    * Additional names that invoke this command.
    *
-   * Aliases are functional at runtime and are suggested by shell completion,
-   * but are hidden from usage and documentation output.  The `name` parameter
-   * passed to {@link command} remains the canonical display name.
+   * Aliases are functional at runtime and are suggested by shell completion.
+   * By default they are hidden from usage and documentation output; set
+   * {@link showAliases} or the help formatter's `showAliases` option to list
+   * them next to the command in command lists.  Usage lines always show
+   * only the `name` parameter passed to {@link command}, which remains the
+   * canonical display name.
    *
    * @since 1.1.0
    */
   readonly aliases?: readonly [string, ...string[]];
+  /**
+   * Whether to show {@link aliases} next to this command in command lists
+   * of help and documentation output, e.g., `(aliases: i, add)`.
+   *
+   * When omitted, the help formatter's `showAliases` option decides, which
+   * defaults to hiding aliases.  `true` shows them and `false` hides them
+   * regardless of that option.  This setting does not affect usage lines
+   * and does not apply to nested subcommands.
+   *
+   * @since 1.4.0
+   */
+  readonly showAliases?: boolean;
   /**
    * Error messages customization.
    * @since 0.5.0
@@ -522,6 +537,7 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  *          to the inner parser for the remaining arguments.
  * @throws {TypeError} If `name` is empty, whitespace-only, contains
  *         embedded whitespace, or contains control characters.
+ * @throws {TypeError} If `options.showAliases` is present but not a boolean.
  */
 declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): FluentParser<M, T, CommandState<TState>>;
 /**

package/dist/primitives.js

@@ -1429,6 +1429,12 @@ function getVisibleCommandAliases(options) {
 	if (!isNonEmptyStringArray(aliases)) throw new TypeError("Command aliases must be a non-empty array of strings.");
 	return aliases;
 }
+function getShowCommandAliases(options) {
+	const showAliases = options.showAliases;
+	if (showAliases == null) return void 0;
+	if (typeof showAliases !== "boolean") throw new TypeError("Command showAliases must be a boolean.");
+	return showAliases;
+}
 function getHiddenCommandAliases(options) {
 	const hiddenAliases = options[hiddenCommandAliasesKey];
 	if (hiddenAliases == null) return [];
@@ -1493,10 +1499,12 @@ async function* suggestCommandAsync(context, prefix, name, aliases, parser, opti
 *          to the inner parser for the remaining arguments.
 * @throws {TypeError} If `name` is empty, whitespace-only, contains
 *         embedded whitespace, or contains control characters.
+* @throws {TypeError} If `options.showAliases` is present but not a boolean.
 */
 function command(name, parser, options = {}) {
 	const commandNames = getCommandNames(name, options);
 	const aliases = getVisibleCommandAliases(options);
+	const showAliases = getShowCommandAliases(options);
 	const hiddenAliases = getHiddenCommandAliases(options);
 	validateCommandNames(commandNames, "Command");
 	validateUniqueCommandNames(commandNames);
@@ -1697,9 +1705,11 @@ function command(name, parser, options = {}) {
 						type: "entry",
 						term: {
 							type: "command",
-							name
+							name,
+							...aliases.length > 0 && { aliases }
 						},
-						description: options.brief ?? options.description
+						description: options.brief ?? options.description,
+						...showAliases != null && { showAliases }
 					}]
 				};
 			}

package/dist/terminal-internal.cjs

@@ -288,7 +288,8 @@ function cacheTerminalTheme(theme = {}) {
 		annotationStyles: theme.annotationStyles == null ? void 0 : {
 			default: theme.annotationStyles.default == null ? void 0 : { ...theme.annotationStyles.default },
 			choices: theme.annotationStyles.choices == null ? void 0 : { ...theme.annotationStyles.choices },
-			environment: theme.annotationStyles.environment == null ? void 0 : { ...theme.annotationStyles.environment }
+			environment: theme.annotationStyles.environment == null ? void 0 : { ...theme.annotationStyles.environment },
+			aliases: theme.annotationStyles.aliases == null ? void 0 : { ...theme.annotationStyles.aliases }
 		}
 	};
 }

package/dist/terminal-internal.js

@@ -288,7 +288,8 @@ function cacheTerminalTheme(theme = {}) {
 		annotationStyles: theme.annotationStyles == null ? void 0 : {
 			default: theme.annotationStyles.default == null ? void 0 : { ...theme.annotationStyles.default },
 			choices: theme.annotationStyles.choices == null ? void 0 : { ...theme.annotationStyles.choices },
-			environment: theme.annotationStyles.environment == null ? void 0 : { ...theme.annotationStyles.environment }
+			environment: theme.annotationStyles.environment == null ? void 0 : { ...theme.annotationStyles.environment },
+			aliases: theme.annotationStyles.aliases == null ? void 0 : { ...theme.annotationStyles.aliases }
 		}
 	};
 }

package/dist/terminal.cjs

@@ -50,7 +50,7 @@ const defaultTerminalTheme = {
 		children: [plain(ctx.text)]
 	}),
 	programName: (_term, ctx) => styled(ctx.text, { bold: true }),
-	label: (term, ctx) => term.kind === "usageSummary" || term.kind === "choices" ? plain(ctx.text) : styled(ctx.text, {
+	label: (term, ctx) => term.kind === "usageSummary" || term.kind === "choices" || term.kind === "aliases" ? plain(ctx.text) : styled(ctx.text, {
 		bold: true,
 		dim: true
 	}),
@@ -60,7 +60,9 @@ const defaultTerminalTheme = {
 		"defaultPrefix",
 		"defaultSuffix",
 		"choicesPrefix",
-		"choicesSuffix"
+		"choicesSuffix",
+		"aliasesPrefix",
+		"aliasesSuffix"
 	].includes(term.kind) ? plain(ctx.text) : styled(ctx.text, { dim: true }),
 	errorLabel: (_term, ctx) => plain(ctx.text),
 	annotationStyles: {

package/dist/terminal.d.cts

@@ -17,7 +17,8 @@ interface ProgramNameTerm {
 interface LabelTerm {
   readonly type: "label";
   readonly label: string;
-  readonly kind: "usage" | "usageSummary" | "section" | "examples" | "author" | "bugs" | "choices";
+  readonly kind: "usage" | "usageSummary" | "section" | "examples" | "author" | "bugs" | "choices"
+  /** Command alias annotation label. @since 1.4.0 */ | "aliases";
 }
 /**
  * Punctuation supplied by a terminal renderer.
@@ -26,7 +27,9 @@ interface LabelTerm {
 interface SyntaxPunctuationTerm {
   readonly type: "syntaxPunctuation";
   readonly punctuation: string;
-  readonly kind: "optionalOpen" | "optionalClose" | "groupOpen" | "groupClose" | "alternative" | "ellipsis" | "passthrough" | "optionSeparator" | "messageOptionSeparator" | "defaultPrefix" | "defaultSuffix" | "choicesPrefix" | "choicesSuffix";
+  readonly kind: "optionalOpen" | "optionalClose" | "groupOpen" | "groupClose" | "alternative" | "ellipsis" | "passthrough" | "optionSeparator" | "messageOptionSeparator" | "defaultPrefix" | "defaultSuffix" | "choicesPrefix" | "choicesSuffix"
+  /** Command alias annotation prefix. @since 1.4.0 */ | "aliasesPrefix"
+  /** Command alias annotation suffix. @since 1.4.0 */ | "aliasesSuffix";
 }
 /**
  * The label preceding an error message.
@@ -116,6 +119,8 @@ type TerminalTheme = Partial<Formatters> & {
     readonly choices?: TerminalStyle;
     /** Environment annotation style. @since 1.4.0 */
     readonly environment?: TerminalStyle;
+    /** Command alias annotation style. @since 1.4.0 */
+    readonly aliases?: TerminalStyle;
   };
 };
 /**

package/dist/terminal.d.ts

@@ -17,7 +17,8 @@ interface ProgramNameTerm {
 interface LabelTerm {
   readonly type: "label";
   readonly label: string;
-  readonly kind: "usage" | "usageSummary" | "section" | "examples" | "author" | "bugs" | "choices";
+  readonly kind: "usage" | "usageSummary" | "section" | "examples" | "author" | "bugs" | "choices"
+  /** Command alias annotation label. @since 1.4.0 */ | "aliases";
 }
 /**
  * Punctuation supplied by a terminal renderer.
@@ -26,7 +27,9 @@ interface LabelTerm {
 interface SyntaxPunctuationTerm {
   readonly type: "syntaxPunctuation";
   readonly punctuation: string;
-  readonly kind: "optionalOpen" | "optionalClose" | "groupOpen" | "groupClose" | "alternative" | "ellipsis" | "passthrough" | "optionSeparator" | "messageOptionSeparator" | "defaultPrefix" | "defaultSuffix" | "choicesPrefix" | "choicesSuffix";
+  readonly kind: "optionalOpen" | "optionalClose" | "groupOpen" | "groupClose" | "alternative" | "ellipsis" | "passthrough" | "optionSeparator" | "messageOptionSeparator" | "defaultPrefix" | "defaultSuffix" | "choicesPrefix" | "choicesSuffix"
+  /** Command alias annotation prefix. @since 1.4.0 */ | "aliasesPrefix"
+  /** Command alias annotation suffix. @since 1.4.0 */ | "aliasesSuffix";
 }
 /**
  * The label preceding an error message.
@@ -116,6 +119,8 @@ type TerminalTheme = Partial<Formatters> & {
     readonly choices?: TerminalStyle;
     /** Environment annotation style. @since 1.4.0 */
     readonly environment?: TerminalStyle;
+    /** Command alias annotation style. @since 1.4.0 */
+    readonly aliases?: TerminalStyle;
   };
 };
 /**

package/dist/terminal.js

@@ -49,7 +49,7 @@ const defaultTerminalTheme = {
 		children: [plain(ctx.text)]
 	}),
 	programName: (_term, ctx) => styled(ctx.text, { bold: true }),
-	label: (term, ctx) => term.kind === "usageSummary" || term.kind === "choices" ? plain(ctx.text) : styled(ctx.text, {
+	label: (term, ctx) => term.kind === "usageSummary" || term.kind === "choices" || term.kind === "aliases" ? plain(ctx.text) : styled(ctx.text, {
 		bold: true,
 		dim: true
 	}),
@@ -59,7 +59,9 @@ const defaultTerminalTheme = {
 		"defaultPrefix",
 		"defaultSuffix",
 		"choicesPrefix",
-		"choicesSuffix"
+		"choicesSuffix",
+		"aliasesPrefix",
+		"aliasesSuffix"
 	].includes(term.kind) ? plain(ctx.text) : styled(ctx.text, { dim: true }),
 	errorLabel: (_term, ctx) => plain(ctx.text),
 	annotationStyles: {

package/dist/usage.d.cts

@@ -108,7 +108,9 @@ type UsageTerm =
   /**
    * Additional command names that invoke the same parser.
    * These aliases participate in parsing, completion, and typo
-   * suggestions, but are not rendered in usage or documentation output.
+   * suggestions.  They are never rendered in usage lines, and are rendered
+   * in documentation command lists only when enabled through
+   * `DocEntry.showAliases` or the `showAliases` formatting option.
    * @since 1.1.0
    */
   readonly aliases?: readonly string[];

package/dist/usage.d.ts

@@ -108,7 +108,9 @@ type UsageTerm =
   /**
    * Additional command names that invoke the same parser.
    * These aliases participate in parsing, completion, and typo
-   * suggestions, but are not rendered in usage or documentation output.
+   * suggestions.  They are never rendered in usage lines, and are rendered
+   * in documentation command lists only when enabled through
+   * `DocEntry.showAliases` or the `showAliases` formatting option.
    * @since 1.1.0
    */
   readonly aliases?: readonly string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2678",
+  "version": "1.4.0-dev.2679",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2678+a475f32a",
+    "@optique/env": "1.4.0-dev.2679+3a3a57d2",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",