From 72446f419f92a091f7b37f555664a216836a9402 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 22 Feb 2026 20:04:08 +0100 Subject: [PATCH] docs: align CLI docs and help surface --- docs/cli/clawbot.md | 21 ++++++++++++++++ docs/cli/completion.md | 35 ++++++++++++++++++++++++++ docs/cli/daemon.md | 43 ++++++++++++++++++++++++++++++++ docs/cli/index.md | 18 +++++++++++++ docs/cli/qr.md | 39 +++++++++++++++++++++++++++++ docs/docs.json | 15 ++++++++++- src/cli/clawbot-cli.ts | 11 +++++++- src/cli/completion-cli.ts | 7 ++++++ src/cli/qr-cli.ts | 5 ++++ src/commands/onboard-channels.ts | 4 +-- 10 files changed, 194 insertions(+), 4 deletions(-) create mode 100644 docs/cli/clawbot.md create mode 100644 docs/cli/completion.md create mode 100644 docs/cli/daemon.md create mode 100644 docs/cli/qr.md diff --git a/docs/cli/clawbot.md b/docs/cli/clawbot.md new file mode 100644 index 00000000000..99468b45456 --- /dev/null +++ b/docs/cli/clawbot.md @@ -0,0 +1,21 @@ +--- +summary: "CLI reference for `openclaw clawbot` (legacy alias namespace)" +read_when: + - You maintain older scripts using `openclaw clawbot ...` + - You need migration guidance to current commands +title: "clawbot" +--- + +# `openclaw clawbot` + +Legacy alias namespace kept for backwards compatibility. + +Current supported alias: + +- `openclaw clawbot qr` (same behavior as [`openclaw qr`](/cli/qr)) + +## Migration + +Prefer modern top-level commands directly: + +- `openclaw clawbot qr` -> `openclaw qr` diff --git a/docs/cli/completion.md b/docs/cli/completion.md new file mode 100644 index 00000000000..7c052a6b25b --- /dev/null +++ b/docs/cli/completion.md @@ -0,0 +1,35 @@ +--- +summary: "CLI reference for `openclaw completion` (generate/install shell completion scripts)" +read_when: + - You want shell completions for zsh/bash/fish/PowerShell + - You need to cache completion scripts under OpenClaw state +title: "completion" +--- + +# `openclaw completion` + +Generate shell completion scripts and optionally install them into your shell profile. + +## Usage + +```bash +openclaw completion +openclaw completion --shell zsh +openclaw completion --install +openclaw completion --shell fish --install +openclaw completion --write-state +openclaw completion --shell bash --write-state +``` + +## Options + +- `-s, --shell `: shell target (`zsh`, `bash`, `powershell`, `fish`; default: `zsh`) +- `-i, --install`: install completion by adding a source line to your shell profile +- `--write-state`: write completion script(s) to `$OPENCLAW_STATE_DIR/completions` without printing to stdout +- `-y, --yes`: skip install confirmation prompts + +## Notes + +- `--install` writes a small "OpenClaw Completion" block into your shell profile and points it at the cached script. +- Without `--install` or `--write-state`, the command prints the script to stdout. +- Completion generation eagerly loads command trees so nested subcommands are included. diff --git a/docs/cli/daemon.md b/docs/cli/daemon.md new file mode 100644 index 00000000000..4b5ebf45d07 --- /dev/null +++ b/docs/cli/daemon.md @@ -0,0 +1,43 @@ +--- +summary: "CLI reference for `openclaw daemon` (legacy alias for gateway service management)" +read_when: + - You still use `openclaw daemon ...` in scripts + - You need service lifecycle commands (install/start/stop/restart/status) +title: "daemon" +--- + +# `openclaw daemon` + +Legacy alias for Gateway service management commands. + +`openclaw daemon ...` maps to the same service control surface as `openclaw gateway ...` service commands. + +## Usage + +```bash +openclaw daemon status +openclaw daemon install +openclaw daemon start +openclaw daemon stop +openclaw daemon restart +openclaw daemon uninstall +``` + +## Subcommands + +- `status`: show service install state and probe Gateway health +- `install`: install service (`launchd`/`systemd`/`schtasks`) +- `uninstall`: remove service +- `start`: start service +- `stop`: stop service +- `restart`: restart service + +## Common options + +- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--deep`, `--json` +- `install`: `--port`, `--runtime `, `--token`, `--force`, `--json` +- lifecycle (`uninstall|start|stop|restart`): `--json` + +## Prefer + +Use [`openclaw gateway`](/cli/gateway) for current docs and examples. diff --git a/docs/cli/index.md b/docs/cli/index.md index 65448f4ee18..3782fae7927 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -16,6 +16,7 @@ This page describes the current CLI behavior. If commands change, update this do - [`onboard`](/cli/onboard) - [`configure`](/cli/configure) - [`config`](/cli/config) +- [`completion`](/cli/completion) - [`doctor`](/cli/doctor) - [`dashboard`](/cli/dashboard) - [`reset`](/cli/reset) @@ -33,6 +34,7 @@ This page describes the current CLI behavior. If commands change, update this do - [`system`](/cli/system) - [`models`](/cli/models) - [`memory`](/cli/memory) +- [`directory`](/cli/directory) - [`nodes`](/cli/nodes) - [`devices`](/cli/devices) - [`node`](/cli/node) @@ -46,10 +48,13 @@ This page describes the current CLI behavior. If commands change, update this do - [`hooks`](/cli/hooks) - [`webhooks`](/cli/webhooks) - [`pairing`](/cli/pairing) +- [`qr`](/cli/qr) - [`plugins`](/cli/plugins) (plugin commands) - [`channels`](/cli/channels) - [`security`](/cli/security) - [`skills`](/cli/skills) +- [`daemon`](/cli/daemon) (legacy alias for gateway service commands) +- [`clawbot`](/cli/clawbot) (legacy alias namespace) - [`voicecall`](/cli/voicecall) (plugin; if installed) ## Global flags @@ -94,7 +99,9 @@ openclaw [--dev] [--profile ] get set unset + completion doctor + dashboard security audit reset @@ -108,6 +115,7 @@ openclaw [--dev] [--profile ] remove login logout + directory skills list info @@ -145,6 +153,13 @@ openclaw [--dev] [--profile ] stop restart run + daemon + status + install + uninstall + start + stop + restart logs system event @@ -231,6 +246,9 @@ openclaw [--dev] [--profile ] pairing list approve + qr + clawbot + qr docs dns setup diff --git a/docs/cli/qr.md b/docs/cli/qr.md new file mode 100644 index 00000000000..109628264f6 --- /dev/null +++ b/docs/cli/qr.md @@ -0,0 +1,39 @@ +--- +summary: "CLI reference for `openclaw qr` (generate iOS pairing QR + setup code)" +read_when: + - You want to pair the iOS app with a gateway quickly + - You need setup-code output for remote/manual sharing +title: "qr" +--- + +# `openclaw qr` + +Generate an iOS pairing QR and setup code from your current Gateway configuration. + +## Usage + +```bash +openclaw qr +openclaw qr --setup-code-only +openclaw qr --json +openclaw qr --remote +openclaw qr --url wss://gateway.example/ws --token '' +``` + +## Options + +- `--remote`: use `gateway.remote.url` plus remote token/password from config +- `--url `: override gateway URL used in payload +- `--public-url `: override public URL used in payload +- `--token `: override gateway token for payload +- `--password `: override gateway password for payload +- `--setup-code-only`: print only setup code +- `--no-ascii`: skip ASCII QR rendering +- `--json`: emit JSON (`setupCode`, `gatewayUrl`, `auth`, `urlSource`) + +## Notes + +- `--token` and `--password` are mutually exclusive. +- After scanning, approve device pairing with: + - `openclaw devices list` + - `openclaw devices approve ` diff --git a/docs/docs.json b/docs/docs.json index 60417533713..bdbaa78c62e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -271,6 +271,10 @@ "source": "/start/clawd/", "destination": "/start/openclaw" }, + { + "source": "/start/pairing", + "destination": "/channels/pairing" + }, { "source": "/clawhub", "destination": "/tools/clawhub" @@ -1182,14 +1186,20 @@ "group": "CLI commands", "pages": [ "cli/index", + "cli/acp", "cli/agent", "cli/agents", "cli/approvals", "cli/browser", "cli/channels", + "cli/clawbot", + "cli/completion", + "cli/config", "cli/configure", "cli/cron", + "cli/daemon", "cli/dashboard", + "cli/devices", "cli/directory", "cli/dns", "cli/docs", @@ -1201,10 +1211,12 @@ "cli/memory", "cli/message", "cli/models", + "cli/node", "cli/nodes", "cli/onboard", "cli/pairing", "cli/plugins", + "cli/qr", "cli/reset", "cli/sandbox", "cli/security", @@ -1216,7 +1228,8 @@ "cli/tui", "cli/uninstall", "cli/update", - "cli/voicecall" + "cli/voicecall", + "cli/webhooks" ] }, { diff --git a/src/cli/clawbot-cli.ts b/src/cli/clawbot-cli.ts index b4c82a5582a..fc49efb9c2a 100644 --- a/src/cli/clawbot-cli.ts +++ b/src/cli/clawbot-cli.ts @@ -1,7 +1,16 @@ import type { Command } from "commander"; +import { formatDocsLink } from "../terminal/links.js"; +import { theme } from "../terminal/theme.js"; import { registerQrCli } from "./qr-cli.js"; export function registerClawbotCli(program: Command) { - const clawbot = program.command("clawbot").description("Legacy clawbot command aliases"); + const clawbot = program + .command("clawbot") + .description("Legacy clawbot command aliases") + .addHelpText( + "after", + () => + `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/clawbot", "docs.openclaw.ai/cli/clawbot")}\n`, + ); registerQrCli(clawbot); } diff --git a/src/cli/completion-cli.ts b/src/cli/completion-cli.ts index 8c14f2979bd..01cd02c018c 100644 --- a/src/cli/completion-cli.ts +++ b/src/cli/completion-cli.ts @@ -4,6 +4,8 @@ import path from "node:path"; import { Command, Option } from "commander"; import { resolveStateDir } from "../config/paths.js"; import { routeLogsToStderr } from "../logging/console.js"; +import { formatDocsLink } from "../terminal/links.js"; +import { theme } from "../terminal/theme.js"; import { pathExists } from "../utils.js"; import { buildFishOptionCompletionLine, @@ -230,6 +232,11 @@ export function registerCompletionCli(program: Command) { program .command("completion") .description("Generate shell completion script") + .addHelpText( + "after", + () => + `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/completion", "docs.openclaw.ai/cli/completion")}\n`, + ) .addOption( new Option("-s, --shell ", "Shell to generate completion for (default: zsh)").choices( COMPLETION_SHELLS, diff --git a/src/cli/qr-cli.ts b/src/cli/qr-cli.ts index 947a24b2dd8..e66f17b9f02 100644 --- a/src/cli/qr-cli.ts +++ b/src/cli/qr-cli.ts @@ -4,6 +4,7 @@ import { loadConfig } from "../config/config.js"; import { resolvePairingSetupFromConfig, encodePairingSetupCode } from "../pairing/setup-code.js"; import { runCommandWithTimeout } from "../process/exec.js"; import { defaultRuntime } from "../runtime.js"; +import { formatDocsLink } from "../terminal/links.js"; import { theme } from "../terminal/theme.js"; type QrCliOptions = { @@ -38,6 +39,10 @@ export function registerQrCli(program: Command) { program .command("qr") .description("Generate an iOS pairing QR code and setup code") + .addHelpText( + "after", + () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/qr", "docs.openclaw.ai/cli/qr")}\n`, + ) .option( "--remote", "Use gateway.remote.url and gateway.remote token/password (ignores device-pair publicUrl)", diff --git a/src/commands/onboard-channels.ts b/src/commands/onboard-channels.ts index a2c3092f1ea..1ac763d9f01 100644 --- a/src/commands/onboard-channels.ts +++ b/src/commands/onboard-channels.ts @@ -197,7 +197,7 @@ async function noteChannelPrimer( "Multi-user DMs: run: " + formatCliCommand('openclaw config set session.dmScope "per-channel-peer"') + ' (or "per-account-channel-peer" for multi-account channels) to isolate sessions.', - `Docs: ${formatDocsLink("/start/pairing", "start/pairing")}`, + `Docs: ${formatDocsLink("/channels/pairing", "channels/pairing")}`, "", ...channelLines, ].join("\n"), @@ -253,7 +253,7 @@ async function maybeConfigureDmPolicies(params: { "Multi-user DMs: run: " + formatCliCommand('openclaw config set session.dmScope "per-channel-peer"') + ' (or "per-account-channel-peer" for multi-account channels) to isolate sessions.', - `Docs: ${formatDocsLink("/start/pairing", "start/pairing")}`, + `Docs: ${formatDocsLink("/channels/pairing", "channels/pairing")}`, ].join("\n"), `${policy.label} DM access`, );