Mark required CLI flags in help output

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",

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());