From 39e24c9937552cc68a77973b77792279d217214e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 21 Jan 2026 16:48:31 +0000 Subject: [PATCH] docs: update node CLI references --- CHANGELOG.md | 1 + docs/cli/daemon.md | 2 +- docs/cli/index.md | 35 ++++++---------------- docs/cli/node.md | 24 +++++----------- docs/cli/service.md | 51 --------------------------------- docs/cli/status.md | 2 +- docs/gateway/configuration.md | 2 +- docs/gateway/troubleshooting.md | 2 +- docs/nodes/index.md | 10 +++---- docs/platforms/mac/xpc.md | 4 +-- docs/platforms/macos.md | 2 +- docs/refactor/exec-host.md | 2 +- docs/refactor/strict-config.md | 2 +- docs/tools/exec-approvals.md | 2 +- docs/tools/index.md | 2 +- 15 files changed, 32 insertions(+), 111 deletions(-) delete mode 100644 docs/cli/service.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a9585be95..46f4ac09b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ Docs: https://docs.clawd.bot - CLI: exec approvals mutations render tables instead of raw JSON. - Exec approvals: support wildcard agent allowlists (`*`) across all agents. - Nodes: expose node PATH in status/describe and bootstrap PATH for node-host execution. +- CLI: flatten node service commands under `clawdbot node` and remove `service node` docs. ### Fixes - Nodes tool: include agent/node/gateway context in tool failure logs to speed approval debugging. diff --git a/docs/cli/daemon.md b/docs/cli/daemon.md index 71c43d1f8..d1e8753ed 100644 --- a/docs/cli/daemon.md +++ b/docs/cli/daemon.md @@ -9,7 +9,7 @@ read_when: Manage the Gateway daemon (background service). -Note: `clawdbot service gateway …` is the preferred surface; `daemon` remains +Note: `clawdbot daemon …` is the preferred surface for Gateway service management; `daemon` remains as a legacy alias for compatibility. Related: diff --git a/docs/cli/index.md b/docs/cli/index.md index d12b5e9f8..fdf730e2b 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -29,7 +29,6 @@ This page describes the current CLI behavior. If commands change, update this do - [`sessions`](/cli/sessions) - [`gateway`](/cli/gateway) - [`daemon`](/cli/daemon) -- [`service`](/cli/service) - [`logs`](/cli/logs) - [`models`](/cli/models) - [`memory`](/cli/memory) @@ -146,21 +145,6 @@ clawdbot [--dev] [--profile ] start stop restart - service - gateway - status - install - uninstall - start - stop - restart - node - status - install - uninstall - start - stop - restart logs models list @@ -544,7 +528,7 @@ Options: - `--debug` (alias for `--verbose`) Notes: -- Overview includes Gateway + Node service status when available. +- Overview includes Gateway + node host service status when available. ### Usage tracking Clawdbot can surface provider usage/quota when OAuth/API creds are available. @@ -806,16 +790,13 @@ All `cron` commands accept `--url`, `--token`, `--timeout`, `--expect-final`. [`clawdbot node`](/cli/node). Subcommands: -- `node start --host --port 18790` -- `node service status` -- `node service install [--host ] [--port ] [--tls] [--tls-fingerprint ] [--node-id ] [--display-name ] [--runtime ] [--force]` -- `node service uninstall` -- `node service start` -- `node service stop` -- `node service restart` - -Legacy alias: -- `node daemon …` (same as `node service …`) +- `node run --host --port 18790` +- `node status` +- `node install [--host ] [--port ] [--tls] [--tls-fingerprint ] [--node-id ] [--display-name ] [--runtime ] [--force]` +- `node uninstall` +- `node run` +- `node stop` +- `node restart` ## Nodes diff --git a/docs/cli/node.md b/docs/cli/node.md index c6a070376..ee9893f87 100644 --- a/docs/cli/node.md +++ b/docs/cli/node.md @@ -23,10 +23,10 @@ Common use cases: Execution is still guarded by **exec approvals** and per‑agent allowlists on the node host, so you can keep command access scoped and explicit. -## Start (foreground) +## Run (foreground) ```bash -clawdbot node start --host --port 18790 +clawdbot node run --host --port 18790 ``` Options: @@ -42,9 +42,7 @@ Options: Install a headless node host as a user service. ```bash -clawdbot node service install --host --port 18790 -# or -clawdbot service node install --host --port 18790 +clawdbot node install --host --port 18790 ``` Options: @@ -61,18 +59,10 @@ Manage the service: ```bash clawdbot node status -clawdbot service node status -clawdbot node service status -clawdbot node service start -clawdbot node service stop -clawdbot node service restart -clawdbot node service uninstall -``` - -Legacy alias: - -```bash -clawdbot node daemon status +clawdbot node run +clawdbot node stop +clawdbot node restart +clawdbot node uninstall ``` ## Pairing diff --git a/docs/cli/service.md b/docs/cli/service.md deleted file mode 100644 index a3cf536a2..000000000 --- a/docs/cli/service.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -summary: "CLI reference for `clawdbot service` (manage gateway + node services)" -read_when: - - You want to manage Gateway or node services cross-platform - - You want a single surface for start/stop/install/uninstall ---- - -# `clawdbot service` - -Manage the **Gateway** service and **node host** services. - -Related: -- Gateway daemon (legacy alias): [Daemon](/cli/daemon) -- Node host: [Node](/cli/node) - -## Gateway service - -```bash -clawdbot service gateway status -clawdbot service gateway install --port 18789 -clawdbot service gateway start -clawdbot service gateway stop -clawdbot service gateway restart -clawdbot service gateway uninstall -``` - -Notes: -- `service gateway status` supports `--json` and `--deep` for system checks. -- `service gateway install` supports `--runtime node|bun` and `--token`. - -## Node host service - -```bash -clawdbot service node status -clawdbot service node install --host --port 18790 -clawdbot service node start -clawdbot service node stop -clawdbot service node restart -clawdbot service node uninstall -``` - -Notes: -- `service node install` supports `--runtime node|bun`, `--node-id`, `--display-name`, - and TLS options (`--tls`, `--tls-fingerprint`). - -## Aliases - -- `clawdbot daemon …` → `clawdbot service gateway …` -- `clawdbot node service …` → `clawdbot service node …` -- `clawdbot node status` → `clawdbot service node status` -- `clawdbot node daemon …` → `clawdbot service node …` (legacy) diff --git a/docs/cli/status.md b/docs/cli/status.md index a66dd958a..f2131cbb8 100644 --- a/docs/cli/status.md +++ b/docs/cli/status.md @@ -19,6 +19,6 @@ clawdbot status --usage Notes: - `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal). - Output includes per-agent session stores when multiple agents are configured. -- Overview includes Gateway + Node service install/runtime status when available. +- Overview includes Gateway + node host service install/runtime status when available. - Overview includes update channel + git SHA (for source checkouts). - Update info surfaces in the Overview; if an update is available, status prints a hint to run `clawdbot update` (see [Updating](/install/updating)). diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 8ebcef47a..acf4ee219 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -24,7 +24,7 @@ Unknown keys, malformed types, or invalid values cause the Gateway to **refuse t When validation fails: - The Gateway does not boot. -- Only diagnostic commands are allowed (for example: `clawdbot doctor`, `clawdbot logs`, `clawdbot health`, `clawdbot status`, `clawdbot service`, `clawdbot help`). +- Only diagnostic commands are allowed (for example: `clawdbot doctor`, `clawdbot logs`, `clawdbot health`, `clawdbot status`, `clawdbot daemon`, `clawdbot help`). - Run `clawdbot doctor` to see the exact issues. - Run `clawdbot doctor --fix` (or `--yes`) to apply migrations/repairs. diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index 3065d5754..ccd9c9ea4 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -354,7 +354,7 @@ clawdbot doctor --fix Notes: - `clawdbot doctor` reports every invalid entry. - `clawdbot doctor --fix` applies migrations/repairs and rewrites the config. -- Diagnostic commands like `clawdbot logs`, `clawdbot health`, `clawdbot status`, and `clawdbot service` still run even if the config is invalid. +- Diagnostic commands like `clawdbot logs`, `clawdbot health`, `clawdbot status`, and `clawdbot daemon` still run even if the config is invalid. ### “All models failed” — what should I check first? diff --git a/docs/nodes/index.md b/docs/nodes/index.md index 711049e6b..9096cb7d9 100644 --- a/docs/nodes/index.md +++ b/docs/nodes/index.md @@ -50,14 +50,14 @@ forwards `exec` calls to the **node host** when `host=node` is selected. On the node machine: ```bash -clawdbot node start --host --port 18789 --display-name "Build Node" +clawdbot node run --host --port 18789 --display-name "Build Node" ``` ### Start a node host (service) ```bash -clawdbot node service install --host --port 18789 --display-name "Build Node" -clawdbot node service start +clawdbot node install --host --port 18789 --display-name "Build Node" +clawdbot node start ``` ### Pair + name @@ -71,7 +71,7 @@ clawdbot nodes list ``` Naming options: -- `--display-name` on `clawdbot node start/service install` (persists in `~/.clawdbot/node.json` on the node). +- `--display-name` on `clawdbot node run` / `clawdbot node install` (persists in `~/.clawdbot/node.json` on the node). - `clawdbot nodes rename --node --name "Build Node"` (gateway override). ### Allowlist the commands @@ -281,7 +281,7 @@ or for running a minimal node alongside a server. Start it: ```bash -clawdbot node start --host --port 18790 +clawdbot node run --host --port 18790 ``` Notes: diff --git a/docs/platforms/mac/xpc.md b/docs/platforms/mac/xpc.md index 5aa22b156..4beaf6fa4 100644 --- a/docs/platforms/mac/xpc.md +++ b/docs/platforms/mac/xpc.md @@ -5,7 +5,7 @@ read_when: --- # Clawdbot macOS IPC architecture -**Current model:** a local Unix socket connects the **node service** to the **macOS app** for exec approvals + `system.run`. A `clawdbot-mac` debug CLI exists for discovery/connect checks; agent actions still flow through the Gateway WebSocket and `node.invoke`. UI automation uses PeekabooBridge. +**Current model:** a local Unix socket connects the **node host service** to the **macOS app** for exec approvals + `system.run`. A `clawdbot-mac` debug CLI exists for discovery/connect checks; agent actions still flow through the Gateway WebSocket and `node.invoke`. UI automation uses PeekabooBridge. ## Goals - Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript). @@ -18,7 +18,7 @@ read_when: - Agent actions are performed via `node.invoke` (e.g. `system.run`, `system.notify`, `canvas.*`). ### Node service + app IPC -- A headless node service connects to the Gateway bridge. +- A headless node host service connects to the Gateway bridge. - `system.run` requests are forwarded to the macOS app over a local Unix socket. - The app performs the exec in UI context, prompts if needed, and returns output. diff --git a/docs/platforms/macos.md b/docs/platforms/macos.md index 561e09189..67b7c84cb 100644 --- a/docs/platforms/macos.md +++ b/docs/platforms/macos.md @@ -57,7 +57,7 @@ The macOS app presents itself as a node. Common commands: The node reports a `permissions` map so agents can decide what’s allowed. Node service + app IPC: -- When the headless node service is running (remote mode), it connects to the Gateway WS as a node. +- When the headless node host service is running (remote mode), it connects to the Gateway WS as a node. - `system.run` executes in the macOS app (UI/TCC context) over a local Unix socket; prompts + output stay in-app. Diagram (SCI): diff --git a/docs/refactor/exec-host.md b/docs/refactor/exec-host.md index 9cad8c27b..c71a456ef 100644 --- a/docs/refactor/exec-host.md +++ b/docs/refactor/exec-host.md @@ -30,7 +30,7 @@ read_when: - **Node identity:** use existing `nodeId`. - **Socket auth:** Unix socket + token (cross-platform); split later if needed. - **Node host state:** `~/.clawdbot/node.json` (node id + pairing token). -- **macOS exec host:** run `system.run` inside the macOS app; node service forwards requests over local IPC. +- **macOS exec host:** run `system.run` inside the macOS app; node host service forwards requests over local IPC. - **No XPC helper:** stick to Unix socket + token + peer checks. ## Key concepts diff --git a/docs/refactor/strict-config.md b/docs/refactor/strict-config.md index cfdc0ca7b..01578d2c5 100644 --- a/docs/refactor/strict-config.md +++ b/docs/refactor/strict-config.md @@ -54,7 +54,7 @@ Allowed (diagnostic-only): - `clawdbot health` - `clawdbot help` - `clawdbot status` -- `clawdbot service` +- `clawdbot daemon` Everything else must hard-fail with: “Config invalid. Run `clawdbot doctor --fix`.” diff --git a/docs/tools/exec-approvals.md b/docs/tools/exec-approvals.md index 369a6a408..c6dccaab5 100644 --- a/docs/tools/exec-approvals.md +++ b/docs/tools/exec-approvals.md @@ -23,7 +23,7 @@ Exec approvals are enforced locally on the execution host: - **node host** → node runner (macOS companion app or headless node host) Planned macOS split: -- **node service** forwards `system.run` to the **macOS app** over local IPC. +- **node host service** forwards `system.run` to the **macOS app** over local IPC. - **macOS app** enforces approvals + executes the command in UI context. ## Settings and storage diff --git a/docs/tools/index.md b/docs/tools/index.md index 541195213..ccb0c87c6 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -181,7 +181,7 @@ Notes: - If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`. - `elevated` is gated by `tools.elevated` plus any `agents.list[].tools.elevated` override (both must allow) and is an alias for `host=gateway` + `security=full`. - `elevated` only changes behavior when the agent is sandboxed (otherwise it’s a no-op). -- `host=node` can target a macOS companion app or a headless node host (`clawdbot node start`). +- `host=node` can target a macOS companion app or a headless node host (`clawdbot node run`). - gateway/node approvals and allowlists: [Exec approvals](/tools/exec-approvals). ### `process`