From fdb3ee9e755790be169f83bae92ac6bff65aa3be Mon Sep 17 00:00:00 2001
From: wotan-allfather <wotan-ai@proton.me>
Date: Sat, 7 Feb 2026 07:01:43 +0000
Subject: [PATCH] feat(help): show dependsOn and exclusive in flag help output

Add display of dependsOn and exclusive flag properties in the command help
output. This helps users understand flag dependencies without relying solely
on error messages or descriptions.

Example output:
  --config=<value>  config file
                    <depends on: --environment>
  --quiet           quiet output
                    <exclusive with: --verbose>

Closes #1002
---
 src/help/command.ts                           |  8 +++
 test/help/format-command-with-options.test.ts | 60 +++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/src/help/command.ts b/src/help/command.ts
index 77ceab58..5ed0654f 100644
--- a/src/help/command.ts
+++ b/src/help/command.ts
@@ -217,6 +217,14 @@ export class CommandHelp extends HelpFormatter {
         right += colorize(this.config?.theme?.flagOptions, `\n<options: ${flag.options.join('|')}>`)
       }
 
+      if (flag.dependsOn && flag.dependsOn.length > 0) {
+        right += colorize(this.config?.theme?.flagOptions, `\n<depends on: --${flag.dependsOn.join(', --')}>`)
+      }
+
+      if (flag.exclusive && flag.exclusive.length > 0) {
+        right += colorize(this.config?.theme?.flagOptions, `\n<exclusive with: --${flag.exclusive.join(', --')}>`)
+      }
+
       return [left, colorize(this.config?.theme?.sectionDescription, right.trim())]
     })
   }
diff --git a/test/help/format-command-with-options.test.ts b/test/help/format-command-with-options.test.ts
index 8fcd0364..0ee40c9d 100644
--- a/test/help/format-command-with-options.test.ts
+++ b/test/help/format-command-with-options.test.ts
@@ -460,4 +460,64 @@ EXAMPLES
     $ oclif oclif:command --help`)
     })
   })
+
+  describe('flag dependsOn and exclusive', () => {
+    it('should show dependsOn in flag help', async () => {
+      const cmd = await makeLoadable(
+        makeCommandClass({
+          flags: {
+            environment: flags.string({description: 'environment to deploy to'}),
+            config: flags.string({description: 'config file', dependsOn: ['environment']}),
+          },
+          id: 'apps:deploy',
+        }),
+      )
+      const output = help.formatCommand(cmd)
+      expect(output).to.include('<depends on: --environment>')
+    })
+
+    it('should show exclusive in flag help', async () => {
+      const cmd = await makeLoadable(
+        makeCommandClass({
+          flags: {
+            verbose: flags.boolean({description: 'verbose output'}),
+            quiet: flags.boolean({description: 'quiet output', exclusive: ['verbose']}),
+          },
+          id: 'apps:run',
+        }),
+      )
+      const output = help.formatCommand(cmd)
+      expect(output).to.include('<exclusive with: --verbose>')
+    })
+
+    it('should show multiple dependsOn flags', async () => {
+      const cmd = await makeLoadable(
+        makeCommandClass({
+          flags: {
+            environment: flags.string({description: 'environment'}),
+            region: flags.string({description: 'region'}),
+            config: flags.string({description: 'config file', dependsOn: ['environment', 'region']}),
+          },
+          id: 'apps:deploy',
+        }),
+      )
+      const output = help.formatCommand(cmd)
+      expect(output).to.include('<depends on: --environment, --region>')
+    })
+
+    it('should show multiple exclusive flags', async () => {
+      const cmd = await makeLoadable(
+        makeCommandClass({
+          flags: {
+            json: flags.boolean({description: 'output as json'}),
+            csv: flags.boolean({description: 'output as csv'}),
+            text: flags.boolean({description: 'output as text', exclusive: ['json', 'csv']}),
+          },
+          id: 'apps:list',
+        }),
+      )
+      const output = help.formatCommand(cmd)
+      expect(output).to.include('<exclusive with: --json, --csv>')
+    })
+  })
 })