From dad3192ac3c54f427083c2030151747038bf0760 Mon Sep 17 00:00:00 2001
From: Ben Truyman <ben@truyman.com>
Date: Sun, 25 Jan 2026 16:04:49 -0600
Subject: [PATCH] feat: show default values in option help text

Display default values for options in help output with dimmed styling.
When an option has a default value, append "(default: <value>)" to the
description in a dimmed color to improve user experience.
---
 src/help.ts       |  5 +++-
 test/help.test.ts | 76 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+), 1 deletion(-)

diff --git a/src/help.ts b/src/help.ts
index a3ca5f7..b40ea66 100644
--- a/src/help.ts
+++ b/src/help.ts
@@ -149,7 +149,10 @@ function formatOptionsWithTitle(options: NormalizedOptions, title: string): stri
   for (const { opt, valueSuffix, visualFlag } of entries) {
     const flagPart = formatFlag(opt, valueSuffix);
     const padding = " ".repeat(maxWidth - visualFlag.length + 2);
-    lines.push(`  ${flagPart}${padding}${opt.description ?? ""}`);
+    const description = opt.description ?? "";
+    const defaultSuffix =
+      opt.default !== undefined ? ` ${kleur.dim(`(default: ${opt.default})`)}` : "";
+    lines.push(`  ${flagPart}${padding}${description}${defaultSuffix}`);
   }
 
   return lines;
diff --git a/test/help.test.ts b/test/help.test.ts
index 7b48571..3345483 100644
--- a/test/help.test.ts
+++ b/test/help.test.ts
@@ -461,4 +461,80 @@ ${kleur.bold("Options:")}
       expect(help).toContain("my-cli init myapp");
     });
   });
+
+  describe("default values", () => {
+    it("shows default value for string option", () => {
+      const cmd = command({
+        name: "my-cli",
+        options: {
+          output: { type: "string", default: "out.txt", description: "Output file" },
+        },
+        handler: () => {},
+      });
+
+      const help = cmd.help();
+
+      expect(help).toContain("Output file");
+      expect(help).toContain(kleur.dim("(default: out.txt)"));
+    });
+
+    it("shows default value for number option", () => {
+      const cmd = command({
+        name: "my-cli",
+        options: {
+          port: { type: "number", default: 3000, description: "Port number" },
+        },
+        handler: () => {},
+      });
+
+      const help = cmd.help();
+
+      expect(help).toContain("Port number");
+      expect(help).toContain(kleur.dim("(default: 3000)"));
+    });
+
+    it("shows default value for boolean option", () => {
+      const cmd = command({
+        name: "my-cli",
+        options: {
+          verbose: { type: "boolean", default: true, description: "Verbose mode" },
+        },
+        handler: () => {},
+      });
+
+      const help = cmd.help();
+
+      expect(help).toContain("Verbose mode");
+      expect(help).toContain(kleur.dim("(default: true)"));
+    });
+
+    it("does not show default suffix when no default", () => {
+      const cmd = command({
+        name: "my-cli",
+        options: {
+          port: { type: "number", description: "Port number" },
+        },
+        handler: () => {},
+      });
+
+      const help = cmd.help();
+
+      expect(help).toContain("Port number");
+      expect(help).not.toContain("(default:");
+    });
+
+    it("shows default alongside description", () => {
+      const cmd = command({
+        name: "my-cli",
+        options: {
+          port: { type: "number", default: 8080, description: "Server port" },
+        },
+        handler: () => {},
+      });
+
+      const help = cmd.help();
+
+      expect(help).toContain(`Server port ${kleur.dim("(default: 8080)")}`);
+    });
+  });
 });