let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add colored CLI docs links

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-10 20:50:17 +01:00
parent cf192f8551
commit 1bd5500832
16 changed files with 210 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/docs.json
View File

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

8
src/cli/browser-cli.ts
View File

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

11
src/cli/cron-cli.ts
View File

@@ -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

11
src/cli/daemon-cli.ts
View File

@@ -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

10
src/cli/docs-cli.ts
View File

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

13
src/cli/gateway-cli.ts
View File

@@ -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.

11
src/cli/logs-cli.ts
View File

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

10
src/cli/models-cli.ts
View File

@@ -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

12
src/cli/nodes-cli.ts
View File

@@ -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

27
src/cli/program.ts
View File

@@ -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 =

12
src/cli/providers-cli.ts
View File

@@ -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")

10
src/cli/sandbox-cli.ts
View File

@@ -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 });
});

12
src/cli/skills-cli.ts
View File

@@ -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")

10
src/cli/tui-cli.ts
View File

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

7
src/cli/update-cli.ts
View File

@@ -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 {

69
src/commands/sandbox-explain.ts
View File

@@ -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`);
}