feat: add hideAliases help option

src/flags.ts

@@ -1,4 +1,3 @@
-/* eslint-disable valid-jsdoc */
 import {URL} from 'node:url'
 
 import {CLIError} from './errors'
@@ -140,7 +139,9 @@ export const help = (opts: Partial<BooleanFlag<boolean>> = {}): BooleanFlag<void
     ...opts,
     async parse(_, cmd) {
       const Help = await loadHelpClass(cmd.config)
-      await new Help(cmd.config, cmd.config.pjson.helpOptions).showHelp(cmd.id ? [cmd.id, ...cmd.argv] : cmd.argv)
+      await new Help(cmd.config, cmd.config.pjson.helpOptions ?? cmd.config.pjson.oclif.helpOptions).showHelp(
+        cmd.id ? [cmd.id, ...cmd.argv] : cmd.argv,
+      )
       cmd.exit(0)
     },
   })

src/help/index.ts

@@ -98,12 +98,13 @@ export class Help extends HelpBase {
 
   protected formatCommands(commands: Array<Command.Loadable>): string {
     if (commands.length === 0) return ''
-
     const body = this.renderList(
-      commands.map((c) => {
-        if (this.config.topicSeparator !== ':') c.id = c.id.replaceAll(':', this.config.topicSeparator)
-        return [c.id, this.summary(c)]
-      }),
+      commands
+        .filter((c) => (this.opts.hideAliasesFromRoot ? !c.aliases?.includes(c.id) : true))
+        .map((c) => {
+          if (this.config.topicSeparator !== ':') c.id = c.id.replaceAll(':', this.config.topicSeparator)
+          return [c.id, this.summary(c)]
+        }),
       {
         indentation: 2,
         spacer: '\n',

src/interfaces/help.ts

@@ -4,6 +4,10 @@ export interface HelpOptions {
    * Use docopts as the usage. Defaults to true.
    */
   docopts?: boolean
+  /**
+   * If true, hide command aliases from the root help output. Defaults to false.
+   */
+  hideAliasesFromRoot?: boolean
   /**
    * By default, the command summary is show at the top of the help and as the first line in
    * the command description. Repeating the summary in the command description improves readability

src/main.ts

@@ -70,7 +70,7 @@ export async function run(argv?: string[], options?: Interfaces.LoadOptions): Pr
   // display help version if applicable
   if (helpAddition(argv, config)) {
     const Help = await loadHelpClass(config)
-    const help = new Help(config, config.pjson.helpOptions)
+    const help = new Help(config, config.pjson.helpOptions ?? config.pjson.oclif.helpOptions)
     await help.showHelp(argv)
     await collectPerf()
     return

test/help/fixtures/fixtures.ts

@@ -154,3 +154,12 @@ export class LongDescription extends Command {
     'run'
   }
 }
+
+export class CommandWithAliases extends Command {
+  static aliases = ['bar', 'baz', 'qux']
+  static description = 'This is a command with aliases'
+  static id = 'foo'
+  async run(): Promise<void> {
+    'run'
+  }
+}

test/help/show-help.test.ts

@@ -13,6 +13,7 @@ import {
   AppsDestroy,
   AppsIndex,
   AppsTopic,
+  CommandWithAliases,
   DbCreate,
   DbTopic,
   DeprecateAliases,
@@ -135,6 +136,69 @@ USAGE
 COMMANDS
   apps  List all apps (app index command)`)
     })
+
+  test
+    .loadConfig()
+    .stdout()
+    .do(async (ctx) => {
+      const {config} = ctx
+
+      monkeyPatchCommands(config, [
+        {
+          name: 'plugin-1',
+          commands: [CommandWithAliases],
+          topics: [],
+        },
+      ])
+
+      const help = new TestHelp(config as any, {hideAliasesFromRoot: true})
+      await help.showHelp([])
+    })
+    .it('shows root help without aliases if hideAliasesFromRoot=true', ({stdout, config}) => {
+      expect(stdout.trim()).to.equal(`base library for oclif CLIs
+
+VERSION
+  ${config.userAgent}
+
+USAGE
+  $ oclif [COMMAND]
+
+COMMANDS
+  foo  This is a command with aliases`)
+    })
+
+  test
+    .loadConfig()
+    .stdout()
+    .do(async (ctx) => {
+      const {config} = ctx
+
+      monkeyPatchCommands(config, [
+        {
+          name: 'plugin-1',
+          commands: [CommandWithAliases],
+          topics: [],
+        },
+      ])
+
+      const help = new TestHelp(config as any)
+      await help.showHelp([])
+    })
+    .it('shows root help with aliases commands by default', ({stdout, config}) => {
+      expect(stdout.trim()).to.equal(`base library for oclif CLIs
+
+VERSION
+  ${config.userAgent}
+
+USAGE
+  $ oclif [COMMAND]
+
+COMMANDS
+  bar  This is a command with aliases
+  baz  This is a command with aliases
+  foo  This is a command with aliases
+  qux  This is a command with aliases`)
+    })
 })
 
 describe('showHelp for a topic', () => {

test/integration/util.ts

@@ -113,7 +113,6 @@ export class Executor {
   }
 }
 
-// eslint-disable-next-line valid-jsdoc
 /**
  * Setup for integration tests.
  *