From 542847ae20b5577f2d8f6e9e886ebe505d08792b Mon Sep 17 00:00:00 2001
From: Christian Leopoldseder <christian@leopoldse.dev>
Date: Fri, 11 Sep 2026 23:57:20 +0000
Subject: [PATCH] Mark required CLI flags in help output

Prefix mandatory options with (required) using existing Commander metadata while preserving standard help descriptions and annotations.
---
 apps/cli/src/__tests__/startup-graph.test.ts | 11 +++++++++++
 apps/cli/src/index.ts                        |  8 +++++++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/apps/cli/src/__tests__/startup-graph.test.ts b/apps/cli/src/__tests__/startup-graph.test.ts
index d9122170c1a..bfae22e46c0 100644
--- a/apps/cli/src/__tests__/startup-graph.test.ts
+++ b/apps/cli/src/__tests__/startup-graph.test.ts
@@ -155,6 +155,17 @@ describe("bb startup module graph", () => {
     }
   }, 30_000);
 
+  it("marks mandatory flags in help without marking optional flags", async () => {
+    const spawn = await runCli("source", ["thread", "spawn", "--help"]);
+    expect(spawn.stdout).toMatch(/--project\b[^\n]*\(required\)/);
+    expect(spawn.stdout).toMatch(/--prompt\b[^\n]*\(required\)/);
+    expect(spawn.stdout).not.toMatch(/--provider[^\n]*\(required\)/);
+
+    const list = await runCli("source", ["thread", "list", "--help"]);
+    expect(list.stdout).toMatch(/--project\b/);
+    expect(list.stdout).not.toMatch(/--project\b[^\n]*\(required\)/);
+  }, 30_000);
+
   it("shows and enforces the thread search result limit", async () => {
     const help = await runCli(
       "source",
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index f6a472b5088..4e3d48deec0 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command } from "commander";
+import { Command, Help } from "commander";
 import { maybeReexecViaBbCli } from "./bb-cli-reexec.js";
 import {
   CORE_COMMAND_GROUPS,
@@ -17,6 +17,12 @@ const program = new Command();
 program
   .name("bb")
   .description("BB CLI - manage your AI coding agents")
+  .configureHelp({
+    optionDescription(option) {
+      const description = Help.prototype.optionDescription.call(this, option);
+      return option.mandatory ? `(required) ${description}` : description;
+    },
+  })
   .enablePositionalOptions()
   .version(resolveBbCliVersion());