diff --git a/docs/docs.json b/docs/docs.json index 4441e1d88..33cc7302b 100644 --- a/docs/docs.json +++ b/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" diff --git a/src/cli/browser-cli.ts b/src/cli/browser-cli.ts index 88d6022f5..ba91e3cd7 100644 --- a/src/cli/browser-cli.ts +++ b/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(); diff --git a/src/cli/cron-cli.ts b/src/cli/cron-cli.ts index 636698de4..aa7a4b5c7 100644 --- a/src/cli/cron-cli.ts +++ b/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 diff --git a/src/cli/daemon-cli.ts b/src/cli/daemon-cli.ts index fa9438384..55a8a1450 100644 --- a/src/cli/daemon-cli.ts +++ b/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( - "Manage the Gateway daemon service (launchd/systemd/schtasks)", + .description("Manage the Gateway daemon service (launchd/systemd/schtasks)") + .addHelpText( + "after", + () => + `\n${theme.muted("Docs:")} ${formatDocsLink( + "/gateway", + "docs.clawd.bot/gateway", + )}\n`, ); daemon diff --git a/src/cli/docs-cli.ts b/src/cli/docs-cli.ts index 0afc26424..40c79cc23 100644 --- a/src/cli/docs-cli.ts +++ b/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); diff --git a/src/cli/gateway-cli.ts b/src/cli/gateway-cli.ts index 669b027ac..9ec5860a2 100644 --- a/src/cli/gateway-cli.ts +++ b/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. diff --git a/src/cli/logs-cli.ts b/src/cli/logs-cli.ts index 242aa6b9a..3b59848ba 100644 --- a/src/cli/logs-cli.ts +++ b/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 ", "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); diff --git a/src/cli/models-cli.ts b/src/cli/models-cli.ts index ce897d66d..98a57efa0 100644 --- a/src/cli/models-cli.ts +++ b/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 diff --git a/src/cli/nodes-cli.ts b/src/cli/nodes-cli.ts index 1342383bf..45b22d19c 100644 --- a/src/cli/nodes-cli.ts +++ b/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 diff --git a/src/cli/program.ts b/src/cli/program.ts index 4d78da35b..faccbf2b3 100644 --- a/src/cli/program.ts +++ b/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( - "afterAll", - `\n${theme.heading("Examples:")}\n${fmtExamples}\n`, - ); + program.addHelpText("afterAll", () => { + const docs = formatDocsLink("/cli", "docs.clawd.bot/cli"); + 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 = diff --git a/src/cli/providers-cli.ts b/src/cli/providers-cli.ts index 5a4d07094..bd9a1f4c6 100644 --- a/src/cli/providers-cli.ts +++ b/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") diff --git a/src/cli/sandbox-cli.ts b/src/cli/sandbox-cli.ts index e307d7db1..5768f7e22 100644 --- a/src/cli/sandbox-cli.ts +++ b/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 }); }); diff --git a/src/cli/skills-cli.ts b/src/cli/skills-cli.ts index 7527c4faa..bace0b716 100644 --- a/src/cli/skills-cli.ts +++ b/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") diff --git a/src/cli/tui-cli.ts b/src/cli/tui-cli.ts index 2d82d7a14..24923e2c5 100644 --- a/src/cli/tui-cli.ts +++ b/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 ", "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); diff --git a/src/cli/update-cli.ts b/src/cli/update-cli.ts index 3f05cf0fa..2fe5c3af8 100644 --- a/src/cli/update-cli.ts +++ b/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 { diff --git a/src/commands/sandbox-explain.ts b/src/commands/sandbox-explain.ts index debfc71d0..4d5dae3b8 100644 --- a/src/commands/sandbox-explain.ts +++ b/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(` agentId: ${payload.agentId}`); - lines.push(` sessionKey: ${payload.sessionKey}`); - lines.push(` mainSessionKey: ${payload.mainSessionKey}`); + lines.push(heading("Effective sandbox:")); + lines.push(` ${key("agentId:")} ${value(payload.agentId)}`); + lines.push(` ${key("sessionKey:")} ${value(payload.sessionKey)}`); + 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(` enabled: ${payload.elevated.enabled}`); - lines.push(` provider: ${payload.elevated.provider ?? "(unknown)"}`); - lines.push(` allowedByConfig: ${payload.elevated.allowedByConfig}`); + lines.push(heading("Elevated:")); + lines.push(` ${key("enabled:")} ${bool(payload.elevated.enabled)}`); + lines.push( + ` ${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 - .map((f) => `${f.gate} (${f.key})`) - .join(", ")}`, + ` ${key("failing gates:")} ${warn( + payload.elevated.failures.map((f) => `${f.gate} (${f.key})`).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`); }