feat: add colored CLI docs links

docs/docs.json

@@ -53,6 +53,22 @@
       "source": "/messages/",
       "destination": "/concepts/messages"
     },
+    {
+      "source": "/message",
+      "destination": "/cli/message"
+    },
+    {
+      "source": "/message/",
+      "destination": "/cli/message"
+    },
+    {
+      "source": "/sandbox",
+      "destination": "/cli/sandbox"
+    },
+    {
+      "source": "/sandbox/",
+      "destination": "/cli/sandbox"
+    },
     {
       "source": "/AGENTS.default",
       "destination": "/reference/AGENTS.default"

src/cli/browser-cli.ts

@@ -2,6 +2,8 @@ import type { Command } from "commander";
 
 import { danger } from "../globals.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 import { registerBrowserActionInputCommands } from "./browser-cli-actions-input.js";
 import { registerBrowserActionObserveCommands } from "./browser-cli-actions-observe.js";
 import {
@@ -27,7 +29,11 @@ export function registerBrowserCli(program: Command) {
     .option("--json", "Output machine-readable JSON", false)
     .addHelpText(
       "after",
-      `\nExamples:\n  ${[...browserCoreExamples, ...browserActionExamples].join("\n  ")}\n`,
+      () =>
+        `\nExamples:\n  ${[...browserCoreExamples, ...browserActionExamples].join("\n  ")}\n\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/browser",
+          "docs.clawd.bot/browser",
+        )}\n`,
     )
     .action(() => {
       browser.outputHelp();

src/cli/cron-cli.ts

@@ -2,6 +2,7 @@ import type { Command } from "commander";
 import type { CronJob, CronSchedule } from "../cron/types.js";
 import { danger } from "../globals.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
 import { colorize, isRich, theme } from "../terminal/theme.js";
 import type { GatewayRpcOpts } from "./gateway-rpc.js";
 import { addGatewayClientOptions, callGatewayFromCli } from "./gateway-rpc.js";
@@ -221,7 +222,15 @@ export function registerCronCli(program: Command) {
 
   const cron = program
     .command("cron")
-    .description("Manage cron jobs (via Gateway)");
+    .description("Manage cron jobs (via Gateway)")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/cron-jobs",
+          "docs.clawd.bot/cron-jobs",
+        )}\n`,
+    );
 
   addGatewayClientOptions(
     cron

src/cli/daemon-cli.ts

@@ -48,6 +48,7 @@ import {
 import { pickPrimaryTailnetIPv4 } from "../infra/tailnet.js";
 import { getResolvedLoggerSettings } from "../logging.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
 import { colorize, isRich, theme } from "../terminal/theme.js";
 import { createDefaultDeps } from "./deps.js";
 import { withProgress } from "./progress.js";
@@ -1020,8 +1021,14 @@ export async function runDaemonRestart() {
 export function registerDaemonCli(program: Command) {
   const daemon = program
     .command("daemon")
-    .description(
+    .description("Manage the Gateway daemon service (launchd/systemd/schtasks)")
-      "Manage the Gateway daemon service (launchd/systemd/schtasks)",
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/gateway",
+          "docs.clawd.bot/gateway",
+        )}\n`,
     );
 
   daemon

src/cli/docs-cli.ts

@@ -2,12 +2,22 @@ import type { Command } from "commander";
 
 import { docsSearchCommand } from "../commands/docs.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 
 export function registerDocsCli(program: Command) {
   program
     .command("docs")
     .description("Search the live Clawdbot docs")
     .argument("[query...]", "Search query")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/hubs",
+          "docs.clawd.bot/hubs",
+        )}\n`,
+    )
     .action(async (queryParts: string[]) => {
       try {
         await docsSearchCommand(queryParts, defaultRuntime);

src/cli/gateway-cli.ts

@@ -38,6 +38,7 @@ import {
   setConsoleSubsystemFilter,
 } from "../logging.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
 import { colorize, isRich, theme } from "../terminal/theme.js";
 import { resolveUserPath } from "../utils.js";
 import { forceFreePortAndWait } from "./ports.js";
@@ -865,7 +866,17 @@ function addGatewayRunCommand(
 
 export function registerGatewayCli(program: Command) {
   const gateway = addGatewayRunCommand(
-    program.command("gateway").description("Run the WebSocket Gateway"),
+    program
+      .command("gateway")
+      .description("Run the WebSocket Gateway")
+      .addHelpText(
+        "after",
+        () =>
+          `\n${theme.muted("Docs:")} ${formatDocsLink(
+            "/gateway",
+            "docs.clawd.bot/gateway",
+          )}\n`,
+      ),
   );
 
   // Back-compat: legacy launchd plists used gateway-daemon; keep hidden alias.

src/cli/logs-cli.ts

@@ -3,6 +3,7 @@ import type { Command } from "commander";
 import { buildGatewayConnectionDetails } from "../gateway/call.js";
 import { parseLogLine } from "../logging/parse-log-line.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
 import { colorize, isRich, theme } from "../terminal/theme.js";
 import { addGatewayClientOptions, callGatewayFromCli } from "./gateway-rpc.js";
 
@@ -154,7 +155,15 @@ export function registerLogsCli(program: Command) {
     .option("--interval <ms>", "Polling interval in ms", "1000")
     .option("--json", "Emit JSON log lines", false)
     .option("--plain", "Plain text output (no ANSI styling)", false)
-    .option("--no-color", "Disable ANSI colors");
+    .option("--no-color", "Disable ANSI colors")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/logging",
+          "docs.clawd.bot/logging",
+        )}\n`,
+    );
 
   addGatewayClientOptions(logs);
 

src/cli/models-cli.ts

@@ -25,6 +25,8 @@ import {
   modelsStatusCommand,
 } from "../commands/models.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 
 export function registerModelsCli(program: Command) {
   const models = program
@@ -39,6 +41,14 @@ export function registerModelsCli(program: Command) {
       "--status-plain",
       "Plain output (alias for `models status --plain`)",
       false,
+    )
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/models",
+          "docs.clawd.bot/models",
+        )}\n`,
     );
 
   models

src/cli/nodes-cli.ts

@@ -2,6 +2,8 @@ import fs from "node:fs/promises";
 import type { Command } from "commander";
 import { callGateway, randomIdempotencyKey } from "../gateway/call.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 import {
   type CameraFacing,
   cameraTempPath,
@@ -351,7 +353,15 @@ function validateA2UIJsonl(jsonl: string) {
 export function registerNodesCli(program: Command) {
   const nodes = program
     .command("nodes")
-    .description("Manage gateway-owned node pairing");
+    .description("Manage gateway-owned node pairing")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/nodes",
+          "docs.clawd.bot/nodes",
+        )}\n`,
+    );
 
   nodesCallOpts(
     nodes

src/cli/program.ts

@@ -27,6 +27,7 @@ import {
 import { danger, setVerbose } from "../globals.js";
 import { autoMigrateLegacyState } from "../infra/state-migrations.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
 import { isRich, theme } from "../terminal/theme.js";
 import { VERSION } from "../version.js";
 import {
@@ -186,10 +187,12 @@ export function buildProgram() {
     .map(([cmd, desc]) => `  ${theme.command(cmd)}\n    ${theme.muted(desc)}`)
     .join("\n");
 
-  program.addHelpText(
+  program.addHelpText("afterAll", () => {
-    "afterAll",
+    const docs = formatDocsLink("/cli", "docs.clawd.bot/cli");
-    `\n${theme.heading("Examples:")}\n${fmtExamples}\n`,
+    return `\n${theme.heading("Examples:")}\n${fmtExamples}\n\n${theme.muted(
-  );
+      "Docs:",
+    )} ${docs}\n`;
+  });
 
   program
     .command("setup")
@@ -500,12 +503,15 @@ export function buildProgram() {
     .description("Send messages and provider actions")
     .addHelpText(
       "after",
-      `
+      () =>
+        `
 Examples:
   clawdbot message send --to +15555550123 --message "Hi"
   clawdbot message send --to +15555550123 --message "Hi" --media photo.jpg
   clawdbot message poll --provider discord --to channel:123 --poll-question "Snack?" --poll-option Pizza --poll-option Sushi
-  clawdbot message react --provider discord --to 123 --message-id 456 --emoji "✅"`,
+  clawdbot message react --provider discord --to 123 --message-id 456 --emoji "✅"
+
+${theme.muted("Docs:")} ${formatDocsLink("/message", "docs.clawd.bot/message")}`,
     )
     .action(() => {
       message.help({ error: true });
@@ -1002,13 +1008,18 @@ Examples:
     )
     .addHelpText(
       "after",
-      `
+      () =>
+        `
 Examples:
   clawdbot agent --to +15555550123 --message "status update"
   clawdbot agent --session-id 1234 --message "Summarize inbox" --thinking medium
   clawdbot agent --to +15555550123 --message "Trace logs" --verbose on --json
   clawdbot agent --to +15555550123 --message "Summon reply" --deliver
-`,
+
+${theme.muted("Docs:")} ${formatDocsLink(
+          "/agent-send",
+          "docs.clawd.bot/agent-send",
+        )}`,
     )
     .action(async (opts) => {
       const verboseLevel =

src/cli/providers-cli.ts

@@ -10,6 +10,8 @@ import {
 import { danger } from "../globals.js";
 import { listChatProviders } from "../providers/registry.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 import { hasExplicitOptions } from "./command-options.js";
 import { runProviderLogin, runProviderLogout } from "./provider-auth.js";
 
@@ -43,7 +45,15 @@ export function registerProvidersCli(program: Command) {
   const providers = program
     .command("providers")
     .alias("provider")
-    .description("Manage chat provider accounts");
+    .description("Manage chat provider accounts")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/configuration",
+          "docs.clawd.bot/configuration",
+        )}\n`,
+    );
 
   providers
     .command("list")

src/cli/sandbox-cli.ts

@@ -6,6 +6,8 @@ import {
 } from "../commands/sandbox.js";
 import { sandboxExplainCommand } from "../commands/sandbox-explain.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 
 // --- Types ---
 
@@ -89,6 +91,14 @@ export function registerSandboxCli(program: Command) {
     .command("sandbox")
     .description("Manage sandbox containers (Docker-based agent isolation)")
     .addHelpText("after", EXAMPLES.main)
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/sandbox",
+          "docs.clawd.bot/sandbox",
+        )}\n`,
+    )
     .action(() => {
       sandbox.help({ error: true });
     });

src/cli/skills-cli.ts

@@ -11,6 +11,8 @@ import {
 } from "../agents/skills-status.js";
 import { loadConfig } from "../config/config.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 
 export type SkillsListOptions = {
   json?: boolean;
@@ -352,7 +354,15 @@ export function formatSkillsCheck(
 export function registerSkillsCli(program: Command) {
   const skills = program
     .command("skills")
-    .description("List and inspect available skills");
+    .description("List and inspect available skills")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/skills",
+          "docs.clawd.bot/skills",
+        )}\n`,
+    );
 
   skills
     .command("list")

src/cli/tui-cli.ts

@@ -1,5 +1,7 @@
 import type { Command } from "commander";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 import { runTui } from "../tui/tui.js";
 import { parseTimeoutMs } from "./parse-timeout.js";
 
@@ -25,6 +27,14 @@ export function registerTuiCli(program: Command) {
       "Agent timeout in ms (defaults to agents.defaults.timeoutSeconds)",
     )
     .option("--history-limit <n>", "History entries to load", "200")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/tui",
+          "docs.clawd.bot/tui",
+        )}\n`,
+    )
     .action(async (opts) => {
       try {
         const timeoutMs = parseTimeoutMs(opts.timeoutMs);

src/cli/update-cli.ts

@@ -6,6 +6,7 @@ import {
   type UpdateRunResult,
 } from "../infra/update-runner.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
 import { theme } from "../terminal/theme.js";
 import { runDaemonRestart } from "./daemon-cli.js";
 
@@ -195,7 +196,8 @@ export function registerUpdateCli(program: Command) {
     )
     .addHelpText(
       "after",
-      `
+      () =>
+        `
 Examples:
   clawdbot update                   # Update a source checkout (git)
   clawdbot update --restart         # Update and restart the daemon
@@ -206,7 +208,8 @@ Notes:
   - For git installs: fetches, rebases, installs deps, builds, and runs doctor
   - For npm installs: use npm/pnpm to reinstall (see docs/install/updating.md)
   - Skips update if the working directory has uncommitted changes
-`,
+
+${theme.muted("Docs:")} ${formatDocsLink("/updating", "docs.clawd.bot/updating")}`,
     )
     .action(async (opts) => {
       try {

src/commands/sandbox-explain.ts

@@ -19,6 +19,8 @@ import {
   resolveAgentIdFromSessionKey,
 } from "../routing/session-key.js";
 import type { RuntimeEnv } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { colorize, isRich, theme } from "../terminal/theme.js";
 
 type SandboxExplainOptions = {
   session?: string;
@@ -294,38 +296,61 @@ export async function sandboxExplainCommand(
     return;
   }
 
+  const rich = isRich();
+  const heading = (value: string) => colorize(rich, theme.heading, value);
+  const key = (value: string) => colorize(rich, theme.muted, value);
+  const value = (val: string) => colorize(rich, theme.info, val);
+  const ok = (val: string) => colorize(rich, theme.success, val);
+  const warn = (val: string) => colorize(rich, theme.warn, val);
+  const err = (val: string) => colorize(rich, theme.error, val);
+  const bool = (flag: boolean) => (flag ? ok("true") : err("false"));
+
   const lines: string[] = [];
-  lines.push("Effective sandbox:");
+  lines.push(heading("Effective sandbox:"));
-  lines.push(`  agentId: ${payload.agentId}`);
+  lines.push(`  ${key("agentId:")} ${value(payload.agentId)}`);
-  lines.push(`  sessionKey: ${payload.sessionKey}`);
+  lines.push(`  ${key("sessionKey:")} ${value(payload.sessionKey)}`);
-  lines.push(`  mainSessionKey: ${payload.mainSessionKey}`);
+  lines.push(`  ${key("mainSessionKey:")} ${value(payload.mainSessionKey)}`);
   lines.push(
-    `  runtime: ${payload.sandbox.sessionIsSandboxed ? "sandboxed" : "direct"}`,
+    `  ${key("runtime:")} ${
+      payload.sandbox.sessionIsSandboxed ? warn("sandboxed") : ok("direct")
+    }`,
   );
   lines.push(
-    `  mode=${payload.sandbox.mode} scope=${payload.sandbox.scope} perSession=${payload.sandbox.perSession}`,
+    `  ${key("mode:")} ${value(payload.sandbox.mode)} ${key("scope:")} ${value(
+      payload.sandbox.scope,
+    )} ${key("perSession:")} ${bool(payload.sandbox.perSession)}`,
   );
   lines.push(
-    `  workspaceAccess=${payload.sandbox.workspaceAccess} workspaceRoot=${payload.sandbox.workspaceRoot}`,
+    `  ${key("workspaceAccess:")} ${value(
+      payload.sandbox.workspaceAccess,
+    )} ${key("workspaceRoot:")} ${value(payload.sandbox.workspaceRoot)}`,
   );
   lines.push("");
-  lines.push("Sandbox tool policy:");
+  lines.push(heading("Sandbox tool policy:"));
   lines.push(
-    `  allow (${payload.sandbox.tools.sources.allow.source}): ${payload.sandbox.tools.allow.join(", ") || "(empty)"}`,
+    `  ${key(`allow (${payload.sandbox.tools.sources.allow.source}):`)} ${value(
+      payload.sandbox.tools.allow.join(", ") || "(empty)",
+    )}`,
   );
   lines.push(
-    `  deny  (${payload.sandbox.tools.sources.deny.source}): ${payload.sandbox.tools.deny.join(", ") || "(empty)"}`,
+    `  ${key(`deny  (${payload.sandbox.tools.sources.deny.source}):`)} ${value(
+      payload.sandbox.tools.deny.join(", ") || "(empty)",
+    )}`,
   );
   lines.push("");
-  lines.push("Elevated:");
+  lines.push(heading("Elevated:"));
-  lines.push(`  enabled: ${payload.elevated.enabled}`);
+  lines.push(`  ${key("enabled:")} ${bool(payload.elevated.enabled)}`);
-  lines.push(`  provider: ${payload.elevated.provider ?? "(unknown)"}`);
+  lines.push(
-  lines.push(`  allowedByConfig: ${payload.elevated.allowedByConfig}`);
+    `  ${key("provider:")} ${value(payload.elevated.provider ?? "(unknown)")}`,
+  );
+  lines.push(
+    `  ${key("allowedByConfig:")} ${bool(payload.elevated.allowedByConfig)}`,
+  );
   if (payload.elevated.failures.length > 0) {
     lines.push(
-      `  failing gates: ${payload.elevated.failures
+      `  ${key("failing gates:")} ${warn(
-        .map((f) => `${f.gate} (${f.key})`)
+        payload.elevated.failures.map((f) => `${f.gate} (${f.key})`).join(", "),
-        .join(", ")}`,
+      )}`,
     );
   }
   if (
@@ -334,14 +359,18 @@ export async function sandboxExplainCommand(
   ) {
     lines.push("");
     lines.push(
-      `Hint: sandbox mode is non-main; use main session key to run direct: ${payload.mainSessionKey}`,
+      `${warn("Hint:")} sandbox mode is non-main; use main session key to run direct: ${value(
+        payload.mainSessionKey,
+      )}`,
     );
   }
   lines.push("");
-  lines.push("Fix-it:");
+  lines.push(heading("Fix-it:"));
   for (const key of payload.fixIt) lines.push(`  - ${key}`);
   lines.push("");
-  lines.push(`Docs: ${payload.docsUrl}`);
+  lines.push(
+    `${key("Docs:")} ${formatDocsLink("/sandbox", "docs.clawd.bot/sandbox")}`,
+  );
 
   runtime.log(`${lines.join("\n")}\n`);
 }