docs(cli): add per-command CLI pages

2026-01-15 06:12:54 +00:00
parent 5b23f847d6
commit 0cbfea79fa
58 changed files with 881 additions and 23 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@
 - CLI/Docs: add a web tools configure section for storing Brave API keys and update onboarding tips.
 - Tools: return a setup hint (docs link) when web_search runs without a Brave API key.
 - Browser: add Chrome extension relay takeover mode (toolbar button), plus `clawdbot browser extension install/path` and remote browser control via `clawdbot browser serve` + `browser.controlToken`.
+- CLI/Docs: add per-command CLI doc pages and link them from `clawdbot <command> --help`.

 ### Fixes
 - Browser: add tests for snapshot labels/efficient query params and labeled image responses.
--- a/docs/cli/agent.md
+++ b/docs/cli/agent.md
@@ -0,0 +1,20 @@
+---
+summary: "CLI reference for `clawdbot agent` (send one agent turn via the Gateway)"
+read_when:
+  - You want to run one agent turn from scripts (optionally deliver reply)
+---
+
+# `clawdbot agent`
+
+Run an agent turn via the Gateway (use `--local` for embedded).
+
+Related:
+- Agent send tool: [Agent send](/tools/agent-send)
+
+## Examples
+
+```bash
+clawdbot agent --to +15555550123 --message "status update" --deliver
+clawdbot agent --session-id 1234 --message "Summarize inbox" --thinking medium
+```
+
--- a/docs/cli/agents.md
+++ b/docs/cli/agents.md
@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot agents` (list/add/delete isolated agents)"
+read_when:
+  - You want multiple isolated agents (workspaces + routing + auth)
+---
+
+# `clawdbot agents`
+
+Manage isolated agents (workspaces + auth + routing).
+
+Related:
+- Multi-agent routing: [Multi-Agent Routing](/concepts/multi-agent)
+- Agent workspace: [Agent workspace](/concepts/agent-workspace)
+
+## Examples
+
+```bash
+clawdbot agents list
+clawdbot agents add work --workspace ~/clawd-work
+clawdbot agents delete work
+```
+
--- a/docs/cli/channels.md
+++ b/docs/cli/channels.md
@@ -0,0 +1,44 @@
+---
+summary: "CLI reference for `clawdbot channels` (accounts, status, login/logout, logs)"
+read_when:
+  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage)
+  - You want to check channel status or tail channel logs
+---
+
+# `clawdbot channels`
+
+Manage chat channel accounts and their runtime status on the Gateway.
+
+Related docs:
+- Channel guides: [Channels](/channels/index)
+- Gateway configuration: [Configuration](/gateway/configuration)
+
+## Common commands
+
+```bash
+clawdbot channels list
+clawdbot channels status
+clawdbot channels logs --channel all
+```
+
+## Add / remove accounts
+
+```bash
+clawdbot channels add --channel telegram --token <bot-token>
+clawdbot channels remove --channel telegram --delete
+```
+
+Tip: `clawdbot channels add --help` shows per-channel flags (token, app token, signal-cli paths, etc).
+
+## Login / logout (interactive)
+
+```bash
+clawdbot channels login --channel whatsapp
+clawdbot channels logout --channel whatsapp
+```
+
+## Troubleshooting
+
+- Run `clawdbot status --deep` for a broad probe.
+- Use `clawdbot doctor` for guided fixes.
+
--- a/docs/cli/configure.md
+++ b/docs/cli/configure.md
@@ -0,0 +1,20 @@
+---
+summary: "CLI reference for `clawdbot configure` / `clawdbot config` (interactive configuration prompts)"
+read_when:
+  - You want to tweak credentials, devices, or agent defaults interactively
+---
+
+# `clawdbot configure` (alias: `config`)
+
+Interactive prompt to set up credentials, devices, and agent defaults.
+
+Related:
+- Gateway configuration reference: [Configuration](/gateway/configuration)
+
+## Examples
+
+```bash
+clawdbot configure
+clawdbot configure --section models --section channels
+```
+
--- a/docs/cli/cron.md
+++ b/docs/cli/cron.md
@@ -0,0 +1,16 @@
+---
+summary: "CLI reference for `clawdbot cron` (schedule and run background jobs)"
+read_when:
+  - You want scheduled jobs and wakeups
+  - You’re debugging cron execution and logs
+---
+
+# `clawdbot cron`
+
+Manage cron jobs for the Gateway scheduler.
+
+Related:
+- Cron jobs: [Cron jobs](/automation/cron-jobs)
+
+Tip: run `clawdbot cron --help` for the full command surface.
+
--- a/docs/cli/daemon.md
+++ b/docs/cli/daemon.md
@@ -0,0 +1,17 @@
+---
+summary: "CLI reference for `clawdbot daemon` (install/uninstall/status for the Gateway service)"
+read_when:
+  - You want to run the Gateway as a background service
+  - You’re debugging daemon install, status, or logs
+---
+
+# `clawdbot daemon`
+
+Manage the Gateway daemon (background service).
+
+Related:
+- Gateway CLI: [Gateway](/cli/gateway)
+- macOS platform notes: [macOS](/platforms/macos)
+
+Tip: run `clawdbot daemon --help` for platform-specific flags.
+
--- a/docs/cli/dashboard.md
+++ b/docs/cli/dashboard.md
@@ -0,0 +1,16 @@
+---
+summary: "CLI reference for `clawdbot dashboard` (open the Control UI)"
+read_when:
+  - You want to open the Control UI with your current token
+  - You want to print the URL without launching a browser
+---
+
+# `clawdbot dashboard`
+
+Open the Control UI using your current auth.
+
+```bash
+clawdbot dashboard
+clawdbot dashboard --no-open
+```
+
--- a/docs/cli/dns.md
+++ b/docs/cli/dns.md
@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot dns` (wide-area discovery helpers)"
+read_when:
+  - You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
+  - You’re setting up split DNS for clawdbot.internal
+---
+
+# `clawdbot dns`
+
+DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
+
+Related:
+- Gateway discovery: [Discovery](/gateway/discovery)
+- Wide-area discovery config: [Configuration](/gateway/configuration)
+
+## Setup
+
+```bash
+clawdbot dns setup
+clawdbot dns setup --apply
+```
+
--- a/docs/cli/docs.md
+++ b/docs/cli/docs.md
@@ -0,0 +1,15 @@
+---
+summary: "CLI reference for `clawdbot docs` (search the live docs index)"
+read_when:
+  - You want to search the live Clawdbot docs from the terminal
+---
+
+# `clawdbot docs`
+
+Search the live docs index.
+
+```bash
+clawdbot docs browser extension
+clawdbot docs sandbox allowHostControl
+```
+
--- a/docs/cli/doctor.md
+++ b/docs/cli/doctor.md
@@ -0,0 +1,23 @@
+---
+summary: "CLI reference for `clawdbot doctor` (health checks + guided repairs)"
+read_when:
+  - You have connectivity/auth issues and want guided fixes
+  - You updated and want a sanity check
+---
+
+# `clawdbot doctor`
+
+Health checks + quick fixes for the gateway and channels.
+
+Related:
+- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
+- Security audit: [Security](/gateway/security)
+
+## Examples
+
+```bash
+clawdbot doctor
+clawdbot doctor --repair
+clawdbot doctor --deep
+```
+
--- a/docs/cli/health.md
+++ b/docs/cli/health.md
@@ -0,0 +1,15 @@
+---
+summary: "CLI reference for `clawdbot health` (gateway health endpoint via RPC)"
+read_when:
+  - You want to quickly check the running Gateway’s health
+---
+
+# `clawdbot health`
+
+Fetch health from the running Gateway.
+
+```bash
+clawdbot health
+clawdbot health --json
+```
+
--- a/docs/cli/hooks.md
+++ b/docs/cli/hooks.md
@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot hooks` (Gmail Pub/Sub + webhook helpers)"
+read_when:
+  - You want to wire Gmail Pub/Sub events into Clawdbot hooks
+  - You want to run the gog watch service and renew loop
+---
+
+# `clawdbot hooks`
+
+Webhook helpers and hook-based integrations.
+
+Related:
+- Webhooks: [Webhook](/automation/webhook)
+- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/gmail-pubsub)
+
+## Gmail
+
+```bash
+clawdbot hooks gmail setup --account you@example.com
+clawdbot hooks gmail run
+```
+
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -9,6 +9,43 @@ read_when:

 This page describes the current CLI behavior. If commands change, update this doc.

+## Command pages
+
+- [`setup`](/cli/setup)
+- [`onboard`](/cli/onboard)
+- [`configure`](/cli/configure) (alias: `config`)
+- [`doctor`](/cli/doctor)
+- [`dashboard`](/cli/dashboard)
+- [`reset`](/cli/reset)
+- [`uninstall`](/cli/uninstall)
+- [`update`](/cli/update)
+- [`message`](/cli/message)
+- [`agent`](/cli/agent)
+- [`agents`](/cli/agents)
+- [`status`](/cli/status)
+- [`health`](/cli/health)
+- [`sessions`](/cli/sessions)
+- [`gateway`](/cli/gateway)
+- [`daemon`](/cli/daemon)
+- [`logs`](/cli/logs)
+- [`models`](/cli/models)
+- [`memory`](/cli/memory)
+- [`nodes`](/cli/nodes)
+- [`sandbox`](/cli/sandbox)
+- [`tui`](/cli/tui)
+- [`browser`](/cli/browser)
+- [`wake`](/cli/wake)
+- [`cron`](/cli/cron)
+- [`dns`](/cli/dns)
+- [`docs`](/cli/docs)
+- [`hooks`](/cli/hooks)
+- [`pairing`](/cli/pairing)
+- [`plugins`](/cli/plugins) (plugin commands)
+- [`channels`](/cli/channels)
+- [`security`](/cli/security)
+- [`skills`](/cli/skills)
+- [`voicecall`](/cli/voicecall) (plugin; if installed)
+
 ## Global flags

 - `--dev`: isolate state under `~/.clawdbot-dev` and shift default ports.
--- a/docs/cli/logs.md
+++ b/docs/cli/logs.md
@@ -0,0 +1,23 @@
+---
+summary: "CLI reference for `clawdbot logs` (tail gateway logs via RPC)"
+read_when:
+  - You need to tail Gateway logs remotely (without SSH)
+  - You want JSON log lines for tooling
+---
+
+# `clawdbot logs`
+
+Tail Gateway file logs over RPC (works in remote mode).
+
+Related:
+- Logging overview: [Logging](/logging)
+
+## Examples
+
+```bash
+clawdbot logs
+clawdbot logs --follow
+clawdbot logs --json
+clawdbot logs --limit 500
+```
+
--- a/docs/cli/memory.md
+++ b/docs/cli/memory.md
@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot memory` (status/index/search)"
+read_when:
+  - You want to index or search semantic memory
+  - You’re debugging memory availability or indexing
+---
+
+# `clawdbot memory`
+
+Memory search tools (semantic memory status/index/search).
+
+Related:
+- Memory concept: [Memory](/concepts/memory)
+
+## Examples
+
+```bash
+clawdbot memory status
+clawdbot memory index
+clawdbot memory search "release checklist"
+```
+
--- a/docs/cli/models.md
+++ b/docs/cli/models.md
@@ -0,0 +1,39 @@
+---
+summary: "CLI reference for `clawdbot models` (status/list/set/scan, aliases, fallbacks, auth)"
+read_when:
+  - You want to change default models or view provider auth status
+  - You want to scan available models/providers and debug auth profiles
+---
+
+# `clawdbot models`
+
+Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).
+
+Related:
+- Providers + models: [Models](/providers/models)
+- Provider auth setup: [Getting started](/start/getting-started)
+
+## Common commands
+
+```bash
+clawdbot models status
+clawdbot models list
+clawdbot models set <model-or-alias>
+clawdbot models scan
+```
+
+## Aliases + fallbacks
+
+```bash
+clawdbot models aliases list
+clawdbot models fallbacks list
+```
+
+## Auth profiles
+
+```bash
+clawdbot models auth add
+clawdbot models auth setup-token
+clawdbot models auth paste-token
+```
+
--- a/docs/cli/nodes.md
+++ b/docs/cli/nodes.md
@@ -0,0 +1,32 @@
+---
+summary: "CLI reference for `clawdbot nodes` (list/status/approve/invoke, camera/canvas/screen)"
+read_when:
+  - You’re managing paired nodes (cameras, screen, canvas)
+  - You need to approve requests or invoke node commands
+---
+
+# `clawdbot nodes`
+
+Manage paired nodes (devices) and invoke node capabilities.
+
+Related:
+- Nodes overview: [Nodes](/nodes)
+- Camera: [Camera nodes](/nodes/camera)
+- Images: [Image nodes](/nodes/images)
+
+## Common commands
+
+```bash
+clawdbot nodes list
+clawdbot nodes pending
+clawdbot nodes approve <requestId>
+clawdbot nodes status
+```
+
+## Invoke / run
+
+```bash
+clawdbot nodes invoke --node <id|name|ip> --command <command> --params <json>
+clawdbot nodes run --node <id|name|ip> <command...>
+```
+
--- a/docs/cli/onboard.md
+++ b/docs/cli/onboard.md
@@ -0,0 +1,21 @@
+---
+summary: "CLI reference for `clawdbot onboard` (interactive onboarding wizard)"
+read_when:
+  - You want guided setup for gateway, workspace, auth, channels, and skills
+---
+
+# `clawdbot onboard`
+
+Interactive onboarding wizard (local or remote Gateway setup).
+
+Related:
+- Wizard guide: [Onboarding](/start/onboarding)
+
+## Examples
+
+```bash
+clawdbot onboard
+clawdbot onboard --flow quickstart
+clawdbot onboard --mode remote --remote-url ws://gateway-host:18789
+```
+
--- a/docs/cli/pairing.md
+++ b/docs/cli/pairing.md
@@ -0,0 +1,20 @@
+---
+summary: "CLI reference for `clawdbot pairing` (approve/list pairing requests)"
+read_when:
+  - You’re using pairing-mode DMs and need to approve senders
+---
+
+# `clawdbot pairing`
+
+Approve or inspect DM pairing requests (for channels that support pairing).
+
+Related:
+- Pairing flow: [Pairing](/start/pairing)
+
+## Commands
+
+```bash
+clawdbot pairing list whatsapp
+clawdbot pairing approve whatsapp <code> --notify
+```
+
--- a/docs/cli/plugins.md
+++ b/docs/cli/plugins.md
@@ -0,0 +1,33 @@
+---
+summary: "CLI reference for `clawdbot plugins` (list, install, enable/disable, doctor)"
+read_when:
+  - You want to install or manage in-process Gateway plugins
+  - You want to debug plugin load failures
+---
+
+# `clawdbot plugins`
+
+Manage Gateway plugins/extensions (loaded in-process).
+
+Related:
+- Plugin system: [Plugins](/plugin)
+- Security hardening: [Security](/gateway/security)
+
+## Commands
+
+```bash
+clawdbot plugins list
+clawdbot plugins info <id>
+clawdbot plugins enable <id>
+clawdbot plugins disable <id>
+clawdbot plugins doctor
+```
+
+### Install
+
+```bash
+clawdbot plugins install <npm-spec>
+```
+
+Security note: treat plugin installs like running code. Prefer pinned versions.
+
--- a/docs/cli/reset.md
+++ b/docs/cli/reset.md
@@ -0,0 +1,17 @@
+---
+summary: "CLI reference for `clawdbot reset` (reset local state/config)"
+read_when:
+  - You want to wipe local state while keeping the CLI installed
+  - You want a dry-run of what would be removed
+---
+
+# `clawdbot reset`
+
+Reset local config/state (keeps the CLI installed).
+
+```bash
+clawdbot reset
+clawdbot reset --dry-run
+clawdbot reset --scope config+creds+sessions --yes --non-interactive
+```
+
--- a/docs/cli/security.md
+++ b/docs/cli/security.md
@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot security` (audit and fix common security footguns)"
+read_when:
+  - You want to run a quick security audit on config/state
+  - You want to apply safe “fix” suggestions (chmod, tighten defaults)
+---
+
+# `clawdbot security`
+
+Security tools (audit + optional fixes).
+
+Related:
+- Security guide: [Security](/gateway/security)
+
+## Audit
+
+```bash
+clawdbot security audit
+clawdbot security audit --deep
+clawdbot security audit --fix
+```
+
--- a/docs/cli/sessions.md
+++ b/docs/cli/sessions.md
@@ -0,0 +1,16 @@
+---
+summary: "CLI reference for `clawdbot sessions` (list stored sessions + usage)"
+read_when:
+  - You want to list stored sessions and see recent activity
+---
+
+# `clawdbot sessions`
+
+List stored conversation sessions.
+
+```bash
+clawdbot sessions
+clawdbot sessions --active 120
+clawdbot sessions --json
+```
+
--- a/docs/cli/setup.md
+++ b/docs/cli/setup.md
@@ -0,0 +1,28 @@
+---
+summary: "CLI reference for `clawdbot setup` (initialize config + workspace)"
+read_when:
+  - You’re doing first-run setup without the full onboarding wizard
+  - You want to set the default workspace path
+---
+
+# `clawdbot setup`
+
+Initialize `~/.clawdbot/clawdbot.json` and the agent workspace.
+
+Related:
+- Getting started: [Getting started](/start/getting-started)
+- Wizard: [Onboarding](/start/onboarding)
+
+## Examples
+
+```bash
+clawdbot setup
+clawdbot setup --workspace ~/clawd
+```
+
+To run the wizard via setup:
+
+```bash
+clawdbot setup --wizard
+```
+
--- a/docs/cli/skills.md
+++ b/docs/cli/skills.md
@@ -0,0 +1,25 @@
+---
+summary: "CLI reference for `clawdbot skills` (list/info/check) and skill eligibility"
+read_when:
+  - You want to see which skills are available and ready to run
+  - You want to debug missing binaries/env/config for skills
+---
+
+# `clawdbot skills`
+
+Inspect skills (bundled + workspace + managed overrides) and see what’s eligible vs missing requirements.
+
+Related:
+- Skills system: [Skills](/tools/skills)
+- Skills config: [Skills config](/tools/skills-config)
+- ClawdHub installs: [ClawdHub](/tools/clawdhub)
+
+## Commands
+
+```bash
+clawdbot skills list
+clawdbot skills list --eligible
+clawdbot skills info <name>
+clawdbot skills check
+```
+
--- a/docs/cli/status.md
+++ b/docs/cli/status.md
@@ -0,0 +1,18 @@
+---
+summary: "CLI reference for `clawdbot status` (diagnostics, probes, usage snapshots)"
+read_when:
+  - You want a quick diagnosis of channel health + recent session recipients
+  - You want a pasteable “all” status for debugging
+---
+
+# `clawdbot status`
+
+Diagnostics for channels + sessions.
+
+```bash
+clawdbot status
+clawdbot status --all
+clawdbot status --deep
+clawdbot status --usage
+```
+
--- a/docs/cli/tui.md
+++ b/docs/cli/tui.md
@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot tui` (terminal UI connected to the Gateway)"
+read_when:
+  - You want a terminal UI for the Gateway (remote-friendly)
+  - You want to pass url/token/session from scripts
+---
+
+# `clawdbot tui`
+
+Open the terminal UI connected to the Gateway.
+
+Related:
+- TUI guide: [TUI](/tui)
+
+## Examples
+
+```bash
+clawdbot tui
+clawdbot tui --url ws://127.0.0.1:18789 --token <token>
+clawdbot tui --session main --deliver
+```
+
--- a/docs/cli/uninstall.md
+++ b/docs/cli/uninstall.md
@@ -0,0 +1,17 @@
+---
+summary: "CLI reference for `clawdbot uninstall` (remove gateway service + local data)"
+read_when:
+  - You want to remove the gateway service and/or local state
+  - You want a dry-run first
+---
+
+# `clawdbot uninstall`
+
+Uninstall the gateway service + local data (CLI remains).
+
+```bash
+clawdbot uninstall
+clawdbot uninstall --all --yes
+clawdbot uninstall --dry-run
+```
+
--- a/docs/cli/voicecall.md
+++ b/docs/cli/voicecall.md
@@ -0,0 +1,33 @@
+---
+summary: "CLI reference for `clawdbot voicecall` (voice-call plugin command surface)"
+read_when:
+  - You use the voice-call plugin and want the CLI entry points
+  - You want quick examples for `voicecall call|continue|status|tail|expose`
+---
+
+# `clawdbot voicecall`
+
+`voicecall` is a plugin-provided command. It only appears if the voice-call plugin is installed and enabled.
+
+Primary doc:
+- Voice-call plugin: [Voice Call](/plugins/voice-call)
+
+## Common commands
+
+```bash
+clawdbot voicecall status --call-id <id>
+clawdbot voicecall call --to "+15555550123" --message "Hello" --mode notify
+clawdbot voicecall continue --call-id <id> --message "Any questions?"
+clawdbot voicecall end --call-id <id>
+```
+
+## Exposing webhooks (Tailscale)
+
+```bash
+clawdbot voicecall expose --mode serve
+clawdbot voicecall expose --mode funnel
+clawdbot voicecall unexpose
+```
+
+Security note: only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.
+
--- a/docs/cli/wake.md
+++ b/docs/cli/wake.md
@@ -0,0 +1,35 @@
+---
+summary: "CLI reference for `clawdbot wake` (enqueue a system event and optionally trigger an immediate heartbeat)"
+read_when:
+  - You want to “poke” a running Gateway to process a system event
+  - You use `wake` with cron jobs or remote nodes
+---
+
+# `clawdbot wake`
+
+Enqueue a system event on the Gateway and optionally trigger an immediate heartbeat.
+
+This is a lightweight “poke” for automation flows where you don’t want to run a full command, but you do want the Gateway to react quickly.
+
+Related:
+- Cron jobs: [Cron](/cli/cron)
+- Gateway heartbeat: [Heartbeat](/gateway/heartbeat)
+
+## Common commands
+
+```bash
+clawdbot wake --text "sync"
+clawdbot wake --text "sync" --mode now
+```
+
+## Flags
+
+- `--text <text>`: system event text.
+- `--mode <mode>`: `now` or `next-heartbeat` (default).
+- `--json`: machine-readable output.
+
+## Notes
+
+- Requires a running Gateway reachable by your current config (local or remote).
+- If you’re using sandboxing, `wake` still targets the Gateway; sandboxing does not block the command itself.
+
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -769,9 +769,38 @@
        "group": "CLI",
        "pages": [
          "cli/index",
+          "cli/setup",
+          "cli/onboard",
+          "cli/configure",
+          "cli/doctor",
+          "cli/dashboard",
+          "cli/reset",
+          "cli/uninstall",
          "cli/browser",
          "cli/message",
+          "cli/agent",
+          "cli/agents",
+          "cli/status",
+          "cli/health",
+          "cli/sessions",
+          "cli/channels",
+          "cli/skills",
+          "cli/plugins",
+          "cli/memory",
+          "cli/models",
+          "cli/logs",
+          "cli/nodes",
          "cli/gateway",
+          "cli/daemon",
+          "cli/tui",
+          "cli/voicecall",
+          "cli/wake",
+          "cli/cron",
+          "cli/dns",
+          "cli/docs",
+          "cli/hooks",
+          "cli/pairing",
+          "cli/security",
          "cli/update",
          "cli/sandbox"
        ]
--- a/extensions/voice-call/src/cli.ts
+++ b/extensions/voice-call/src/cli.ts
@@ -42,7 +42,10 @@ export function registerVoiceCallCli(params: {
  logger: Logger;
 }) {
  const { program, config, ensureRuntime, logger } = params;
-  const root = program.command("voicecall").description("Voice call utilities");
+  const root = program
+    .command("voicecall")
+    .description("Voice call utilities")
+    .addHelpText("after", () => `\nDocs: https://docs.clawd.bot/cli/voicecall\n`);

  root
    .command("call")
--- a/src/cli/channels-cli.ts
+++ b/src/cli/channels-cli.ts
@@ -47,8 +47,8 @@ export function registerChannelsCli(program: Command) {
      "after",
      () =>
        `\n${theme.muted("Docs:")} ${formatDocsLink(
-          "/configuration",
-          "docs.clawd.bot/configuration",
+          "/cli/channels",
+          "docs.clawd.bot/cli/channels",
        )}\n`,
    );

--- a/src/cli/cron-cli/register.ts
+++ b/src/cli/cron-cli/register.ts
@@ -18,8 +18,7 @@ export function registerCronCli(program: Command) {
    .description("Manage cron jobs (via Gateway)")
    .addHelpText(
      "after",
-      () =>
-        `\n${theme.muted("Docs:")} ${formatDocsLink("/cron-jobs", "docs.clawd.bot/cron-jobs")}\n`,
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/cron", "docs.clawd.bot/cli/cron")}\n`,
    );

  registerCronStatusCommand(cron);
--- a/src/cli/cron-cli/register.wake.ts
+++ b/src/cli/cron-cli/register.wake.ts
@@ -1,6 +1,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 type { GatewayRpcOpts } from "../gateway-rpc.js";
 import { addGatewayClientOptions, callGatewayFromCli } from "../gateway-rpc.js";

@@ -12,6 +14,10 @@ export function registerWakeCommand(program: Command) {
      .requiredOption("--text <text>", "System event text")
      .option("--mode <mode>", "Wake mode (now|next-heartbeat)", "next-heartbeat")
      .option("--json", "Output JSON", false),
+  )
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/wake", "docs.clawd.bot/cli/wake")}\n`,
  ).action(async (opts: GatewayRpcOpts & { text?: string; mode?: string }) => {
    try {
      const result = await callGatewayFromCli(
--- a/src/cli/daemon-cli/register.ts
+++ b/src/cli/daemon-cli/register.ts
@@ -17,7 +17,8 @@ export function registerDaemonCli(program: Command) {
    .description("Manage the Gateway daemon service (launchd/systemd/schtasks)")
    .addHelpText(
      "after",
-      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/gateway", "docs.clawd.bot/gateway")}\n`,
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/daemon", "docs.clawd.bot/cli/daemon")}\n`,
    );

  daemon
--- a/src/cli/dns-cli.ts
+++ b/src/cli/dns-cli.ts
@@ -7,6 +7,8 @@ import type { Command } from "commander";
 import { loadConfig } from "../config/config.js";
 import { pickPrimaryTailnetIPv4, pickPrimaryTailnetIPv6 } from "../infra/tailnet.js";
 import { getWideAreaZonePath, WIDE_AREA_DISCOVERY_DOMAIN } from "../infra/widearea-dns.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";

 type RunOpts = { allowFailure?: boolean; inherit?: boolean };

@@ -90,7 +92,11 @@ function ensureImportLine(corefilePath: string, importGlob: string): boolean {
 export function registerDnsCli(program: Command) {
  const dns = program
    .command("dns")
-    .description("DNS helpers for wide-area discovery (Tailscale + CoreDNS)");
+    .description("DNS helpers for wide-area discovery (Tailscale + CoreDNS)")
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/dns", "docs.clawd.bot/cli/dns")}\n`,
+    );

  dns
    .command("setup")
--- a/src/cli/docs-cli.ts
+++ b/src/cli/docs-cli.ts
@@ -12,7 +12,7 @@ export function registerDocsCli(program: Command) {
    .argument("[query...]", "Search query")
    .addHelpText(
      "after",
-      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/hubs", "docs.clawd.bot/hubs")}\n`,
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/docs", "docs.clawd.bot/cli/docs")}\n`,
    )
    .action(async (queryParts: string[]) => {
      try {
--- a/src/cli/gateway-cli/register.ts
+++ b/src/cli/gateway-cli/register.ts
@@ -25,7 +25,8 @@ export function registerGatewayCli(program: Command) {
      .description("Run the WebSocket Gateway")
      .addHelpText(
        "after",
-        () => `\n${theme.muted("Docs:")} ${formatDocsLink("/gateway", "docs.clawd.bot/gateway")}\n`,
+        () =>
+          `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/gateway", "docs.clawd.bot/cli/gateway")}\n`,
      ),
  );

--- a/src/cli/hooks-cli.ts
+++ b/src/cli/hooks-cli.ts
@@ -18,9 +18,17 @@ import {
  runGmailSetup,
 } from "../hooks/gmail-ops.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";

 export function registerHooksCli(program: Command) {
-  const hooks = program.command("hooks").description("Webhook helpers and hook-based integrations");
+  const hooks = program
+    .command("hooks")
+    .description("Webhook helpers and hook-based integrations")
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/hooks", "docs.clawd.bot/cli/hooks")}\n`,
+    );

  const gmail = hooks.command("gmail").description("Gmail Pub/Sub hooks (via gogcli)");

--- a/src/cli/logs-cli.ts
+++ b/src/cli/logs-cli.ts
@@ -152,7 +152,7 @@ export function registerLogsCli(program: Command) {
    .option("--no-color", "Disable ANSI colors")
    .addHelpText(
      "after",
-      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/logging", "docs.clawd.bot/logging")}\n`,
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/logs", "docs.clawd.bot/cli/logs")}\n`,
    );

  addGatewayClientOptions(logs);
--- a/src/cli/memory-cli.ts
+++ b/src/cli/memory-cli.ts
@@ -5,6 +5,8 @@ import { resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { loadConfig } from "../config/config.js";
 import { getMemorySearchManager } from "../memory/index.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";

 type MemoryCommandOptions = {
  agent?: string;
@@ -18,7 +20,13 @@ function resolveAgent(cfg: ReturnType<typeof loadConfig>, agent?: string) {
 }

 export function registerMemoryCli(program: Command) {
-  const memory = program.command("memory").description("Memory search tools");
+  const memory = program
+    .command("memory")
+    .description("Memory search tools")
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/memory", "docs.clawd.bot/cli/memory")}\n`,
+    );

  memory
    .command("status")
--- a/src/cli/models-cli.ts
+++ b/src/cli/models-cli.ts
@@ -37,7 +37,8 @@ export function registerModelsCli(program: Command) {
    .option("--status-plain", "Plain output (alias for `models status --plain`)", false)
    .addHelpText(
      "after",
-      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/models", "docs.clawd.bot/models")}\n`,
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/models", "docs.clawd.bot/cli/models")}\n`,
    );

  models
--- a/src/cli/nodes-cli/register.ts
+++ b/src/cli/nodes-cli/register.ts
@@ -16,7 +16,7 @@ export function registerNodesCli(program: Command) {
    .description("Manage gateway-owned node pairing")
    .addHelpText(
      "after",
-      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/nodes", "docs.clawd.bot/nodes")}\n`,
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/nodes", "docs.clawd.bot/cli/nodes")}\n`,
    );

  registerNodesStatusCommands(nodes);
--- a/src/cli/pairing-cli.ts
+++ b/src/cli/pairing-cli.ts
@@ -11,6 +11,8 @@ import {
  listChannelPairingRequests,
  type PairingChannel,
 } from "../pairing/pairing-store.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";

 const CHANNELS: PairingChannel[] = listPairingChannels();

@@ -26,7 +28,12 @@ async function notifyApproved(channel: PairingChannel, id: string) {
 export function registerPairingCli(program: Command) {
  const pairing = program
    .command("pairing")
-    .description("Secure DM pairing (approve inbound requests)");
+    .description("Secure DM pairing (approve inbound requests)")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/pairing", "docs.clawd.bot/cli/pairing")}\n`,
+    );

  pairing
    .command("list")
--- a/src/cli/plugins-cli.ts
+++ b/src/cli/plugins-cli.ts
@@ -54,7 +54,14 @@ function formatPluginLine(plugin: PluginRecord, verbose = false): string {
 }

 export function registerPluginsCli(program: Command) {
-  const plugins = program.command("plugins").description("Manage Clawdbot plugins/extensions");
+  const plugins = program
+    .command("plugins")
+    .description("Manage Clawdbot plugins/extensions")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/plugins", "docs.clawd.bot/cli/plugins")}\n`,
+    );

  plugins
    .command("list")
--- a/src/cli/program/register.agent.ts
+++ b/src/cli/program/register.agent.ts
@@ -48,7 +48,7 @@ Examples:
  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")}`,
+${theme.muted("Docs:")} ${formatDocsLink("/cli/agent", "docs.clawd.bot/cli/agent")}`,
    )
    .action(async (opts) => {
      const verboseLevel = typeof opts.verbose === "string" ? opts.verbose.toLowerCase() : "";
@@ -65,7 +65,11 @@ ${theme.muted("Docs:")} ${formatDocsLink("/agent-send", "docs.clawd.bot/agent-se

  const agents = program
    .command("agents")
-    .description("Manage isolated agents (workspaces + auth + routing)");
+    .description("Manage isolated agents (workspaces + auth + routing)")
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/agents", "docs.clawd.bot/cli/agents")}\n`,
+    );

  agents
    .command("list")
--- a/src/cli/program/register.configure.ts
+++ b/src/cli/program/register.configure.ts
@@ -5,6 +5,8 @@ import {
  configureCommandWithSections,
 } from "../../commands/configure.js";
 import { defaultRuntime } from "../../runtime.js";
+import { formatDocsLink } from "../../terminal/links.js";
+import { theme } from "../../terminal/theme.js";

 export function registerConfigureCommand(program: Command) {
  const register = (name: "configure" | "config") => {
@@ -15,6 +17,11 @@ export function registerConfigureCommand(program: Command) {
          ? "Alias for `clawdbot configure`"
          : "Interactive prompt to set up credentials, devices, and agent defaults",
      )
+      .addHelpText(
+        "after",
+        () =>
+          `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/configure", "docs.clawd.bot/cli/configure")}\n`,
+      )
      .option(
        "--section <section>",
        `Configuration sections (repeatable). Options: ${CONFIGURE_WIZARD_SECTIONS.join(", ")}`,
--- a/src/cli/program/register.maintenance.ts
+++ b/src/cli/program/register.maintenance.ts
@@ -4,11 +4,17 @@ import { doctorCommand } from "../../commands/doctor.js";
 import { resetCommand } from "../../commands/reset.js";
 import { uninstallCommand } from "../../commands/uninstall.js";
 import { defaultRuntime } from "../../runtime.js";
+import { formatDocsLink } from "../../terminal/links.js";
+import { theme } from "../../terminal/theme.js";

 export function registerMaintenanceCommands(program: Command) {
  program
    .command("doctor")
    .description("Health checks + quick fixes for the gateway and channels")
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/doctor", "docs.clawd.bot/cli/doctor")}\n`,
+    )
    .option("--no-workspace-suggestions", "Disable workspace memory system suggestions", false)
    .option("--yes", "Accept defaults without prompting", false)
    .option("--repair", "Apply recommended repairs without prompting", false)
@@ -36,6 +42,11 @@ export function registerMaintenanceCommands(program: Command) {
  program
    .command("dashboard")
    .description("Open the Control UI with your current token")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/dashboard", "docs.clawd.bot/cli/dashboard")}\n`,
+    )
    .option("--no-open", "Print URL but do not launch a browser", false)
    .action(async (opts) => {
      try {
@@ -51,6 +62,10 @@ export function registerMaintenanceCommands(program: Command) {
  program
    .command("reset")
    .description("Reset local config/state (keeps the CLI installed)")
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/reset", "docs.clawd.bot/cli/reset")}\n`,
+    )
    .option("--scope <scope>", "config|config+creds+sessions|full (default: interactive prompt)")
    .option("--yes", "Skip confirmation prompts", false)
    .option("--non-interactive", "Disable prompts (requires --scope + --yes)", false)
@@ -72,6 +87,11 @@ export function registerMaintenanceCommands(program: Command) {
  program
    .command("uninstall")
    .description("Uninstall the gateway service + local data (CLI remains)")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/uninstall", "docs.clawd.bot/cli/uninstall")}\n`,
+    )
    .option("--service", "Remove the gateway service", false)
    .option("--state", "Remove state + config", false)
    .option("--workspace", "Remove workspace dirs", false)
--- a/src/cli/program/register.onboard.ts
+++ b/src/cli/program/register.onboard.ts
@@ -9,6 +9,8 @@ import type {
  TailscaleMode,
 } from "../../commands/onboard-types.js";
 import { defaultRuntime } from "../../runtime.js";
+import { formatDocsLink } from "../../terminal/links.js";
+import { theme } from "../../terminal/theme.js";

 function resolveInstallDaemonFlag(
  command: unknown,
@@ -32,6 +34,11 @@ export function registerOnboardCommand(program: Command) {
  program
    .command("onboard")
    .description("Interactive wizard to set up the gateway, workspace, and skills")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/onboard", "docs.clawd.bot/cli/onboard")}\n`,
+    )
    .option("--workspace <dir>", "Agent workspace directory (default: ~/clawd)")
    .option("--reset", "Reset config + credentials + sessions + workspace before running wizard")
    .option("--non-interactive", "Run without prompts", false)
--- a/src/cli/program/register.setup.ts
+++ b/src/cli/program/register.setup.ts
@@ -2,12 +2,18 @@ import type { Command } from "commander";
 import { onboardCommand } from "../../commands/onboard.js";
 import { setupCommand } from "../../commands/setup.js";
 import { defaultRuntime } from "../../runtime.js";
+import { formatDocsLink } from "../../terminal/links.js";
+import { theme } from "../../terminal/theme.js";
 import { hasExplicitOptions } from "../command-options.js";

 export function registerSetupCommand(program: Command) {
  program
    .command("setup")
    .description("Initialize ~/.clawdbot/clawdbot.json and the agent workspace")
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/setup", "docs.clawd.bot/cli/setup")}\n`,
+    )
    .option(
      "--workspace <dir>",
      "Agent workspace directory (default: ~/clawd; stored as agents.defaults.workspace)",
--- a/src/cli/program/register.status-health-sessions.ts
+++ b/src/cli/program/register.status-health-sessions.ts
@@ -4,6 +4,8 @@ import { sessionsCommand } from "../../commands/sessions.js";
 import { statusCommand } from "../../commands/status.js";
 import { setVerbose } from "../../globals.js";
 import { defaultRuntime } from "../../runtime.js";
+import { formatDocsLink } from "../../terminal/links.js";
+import { theme } from "../../terminal/theme.js";
 import { parsePositiveIntOrUndefined } from "./helpers.js";

 export function registerStatusHealthSessionsCommands(program: Command) {
@@ -29,6 +31,10 @@ Examples:
  clawdbot status --deep --timeout 5000 # tighten probe timeout
  clawdbot channels status          # gateway channel runtime + probes`,
    )
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/status", "docs.clawd.bot/cli/status")}\n`,
+    )
    .action(async (opts) => {
      const verbose = Boolean(opts.verbose || opts.debug);
      setVerbose(verbose);
@@ -63,6 +69,10 @@ Examples:
    .option("--timeout <ms>", "Connection timeout in milliseconds", "10000")
    .option("--verbose", "Verbose logging", false)
    .option("--debug", "Alias for --verbose", false)
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/health", "docs.clawd.bot/cli/health")}\n`,
+    )
    .action(async (opts) => {
      const verbose = Boolean(opts.verbose || opts.debug);
      setVerbose(verbose);
@@ -105,6 +115,11 @@ Examples:

 Shows token usage per session when the agent reports it; set agents.defaults.contextTokens to see % of your model window.`,
    )
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/sessions", "docs.clawd.bot/cli/sessions")}\n`,
+    )
    .action(async (opts) => {
      setVerbose(Boolean(opts.verbose));
      await sessionsCommand(
--- a/src/cli/sandbox-cli.ts
+++ b/src/cli/sandbox-cli.ts
@@ -87,7 +87,8 @@ export function registerSandboxCli(program: Command) {
    .addHelpText("after", EXAMPLES.main)
    .addHelpText(
      "after",
-      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/sandbox", "docs.clawd.bot/sandbox")}\n`,
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/sandbox", "docs.clawd.bot/cli/sandbox")}\n`,
    )
    .action(() => {
      sandbox.help({ error: true });
--- a/src/cli/security-cli.ts
+++ b/src/cli/security-cli.ts
@@ -5,6 +5,7 @@ import { loadConfig } from "../config/config.js";
 import { defaultRuntime } from "../runtime.js";
 import { runSecurityAudit } from "../security/audit.js";
 import { fixSecurityFootguns } from "../security/fix.js";
+import { formatDocsLink } from "../terminal/links.js";
 import { isRich, theme } from "../terminal/theme.js";

 type SecurityAuditOptions = {
@@ -26,7 +27,14 @@ function formatSummary(summary: { critical: number; warn: number; info: number }
 }

 export function registerSecurityCli(program: Command) {
-  const security = program.command("security").description("Security tools (audit)");
+  const security = program
+    .command("security")
+    .description("Security tools (audit)")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/security", "docs.clawd.bot/cli/security")}\n`,
+    );

  security
    .command("audit")
--- a/src/cli/skills-cli.ts
+++ b/src/cli/skills-cli.ts
@@ -334,7 +334,8 @@ export function registerSkillsCli(program: Command) {
    .description("List and inspect available skills")
    .addHelpText(
      "after",
-      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/skills", "docs.clawd.bot/skills")}\n`,
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/skills", "docs.clawd.bot/cli/skills")}\n`,
    );

  skills
--- a/src/cli/tui-cli.ts
+++ b/src/cli/tui-cli.ts
@@ -20,7 +20,7 @@ export function registerTuiCli(program: Command) {
    .option("--history-limit <n>", "History entries to load", "200")
    .addHelpText(
      "after",
-      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/tui", "docs.clawd.bot/tui")}\n`,
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/tui", "docs.clawd.bot/cli/tui")}\n`,
    )
    .action(async (opts) => {
      try {
--- a/src/cli/update-cli.ts
+++ b/src/cli/update-cli.ts
@@ -279,7 +279,7 @@ Notes:
  - For global installs: use npm/pnpm/bun 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")}`,
+${theme.muted("Docs:")} ${formatDocsLink("/cli/update", "docs.clawd.bot/cli/update")}`,
    )
    .action(async (opts) => {
      try {