From e7c355ee85ac7cf0bf4be7377a281ab9a491dbc1 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 21 Jan 2026 03:25:57 +0000
Subject: [PATCH] feat: group service help examples by submenu

---
 src/cli/program/help.ts |  3 ++-
 src/cli/service-cli.ts  | 29 ++++++++++++++++++++++++++++-
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/src/cli/program/help.ts b/src/cli/program/help.ts
index 37ad155d7..c90f9eb96 100644
--- a/src/cli/program/help.ts
+++ b/src/cli/program/help.ts
@@ -80,7 +80,8 @@ export function configureProgramHelp(program: Command, ctx: ProgramContext) {
     ([cmd, desc]) => `  ${theme.command(cmd)}\n    ${theme.muted(desc)}`,
   ).join("\n");
 
-  program.addHelpText("afterAll", () => {
+  program.addHelpText("afterAll", ({ command }) => {
+    if (command !== program) return "";
     const docs = formatDocsLink("/cli", "docs.clawd.bot/cli");
     return `\n${theme.heading("Examples:")}\n${fmtExamples}\n\n${theme.muted("Docs:")} ${docs}\n`;
   });
diff --git a/src/cli/service-cli.ts b/src/cli/service-cli.ts
index 6943f372f..d2dcc376d 100644
--- a/src/cli/service-cli.ts
+++ b/src/cli/service-cli.ts
@@ -20,13 +20,40 @@ import {
 } from "./node-cli/daemon.js";
 
 export function registerServiceCli(program: Command) {
+  const formatExample = (cmd: string, desc: string) =>
+    `  ${theme.command(cmd)}\n    ${theme.muted(desc)}`;
+
+  const formatGroup = (label: string, examples: Array<[string, string]>) =>
+    `${theme.muted(label)}\n${examples.map(([cmd, desc]) => formatExample(cmd, desc)).join("\n")}`;
+
+  const gatewayExamples: Array<[string, string]> = [
+    ["clawdbot service gateway status", "Show gateway service status + probe."],
+    [
+      "clawdbot service gateway install --port 18789 --token <token>",
+      "Install the Gateway service on port 18789.",
+    ],
+    ["clawdbot service gateway restart", "Restart the Gateway service."],
+  ];
+
+  const nodeExamples: Array<[string, string]> = [
+    ["clawdbot service node status", "Show node host service status."],
+    [
+      "clawdbot service node install --host gateway.local --port 18789 --tls",
+      "Install the node host service with TLS.",
+    ],
+    ["clawdbot service node restart", "Restart the node host service."],
+  ];
+
   const service = program
     .command("service")
     .description("Manage Gateway and node host services (launchd/systemd/schtasks)")
     .addHelpText(
       "after",
       () =>
-        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/service", "docs.clawd.bot/cli/service")}\n`,
+        `\n${theme.heading("Examples:")}\n${formatGroup("Gateway:", gatewayExamples)}\n\n${formatGroup(
+          "Node:",
+          nodeExamples,
+        )}\n\n${theme.muted("Docs:")} ${formatDocsLink("/cli/service", "docs.clawd.bot/cli/service")}\n`,
     );
 
   const gateway = service.command("gateway").description("Manage the Gateway service");