refactor: simplify cli commands

2026-01-08 07:16:05 +01:00
parent 79ac0af719
commit 19595a8f99
33 changed files with 359 additions and 1427 deletions
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -42,7 +42,6 @@ clawdbot [--dev] [--profile <name>] <command>
  setup
  onboard
  configure (alias: config)
-  update
  doctor
  login
  logout
@@ -65,12 +64,6 @@ clawdbot [--dev] [--profile <name>] <command>
    call
    health
    status
-    wake
-    send
-    agent
-    stop
-    restart
-  gateway-daemon
  models
    list
    status
@@ -106,13 +99,6 @@ clawdbot [--dev] [--profile <name>] <command>
    canvas snapshot
    screen record
    location get
-  canvas
-    snapshot
-    present
-    hide
-    navigate
-    eval
-    a2ui push|reset
  browser
    status
    start
@@ -198,9 +184,6 @@ Options:
 ### `configure` / `config`
 Interactive configuration wizard (models, providers, skills, gateway).

-### `update`
-Audit and modernize the local configuration.
-
 ### `doctor`
 Health checks + quick fixes (config + gateway + legacy services).

@@ -261,13 +244,6 @@ Subcommands:
 - `pairing list --provider <telegram|signal|imessage|discord|slack|whatsapp> [--json]`
 - `pairing approve --provider <...> <code> [--notify]`

-### `telegram pairing`
-Telegram-only pairing helper.
-
-Subcommands:
- `telegram pairing list [--json]`
- `telegram pairing approve <code> [--no-notify]`
-
 ### `hooks gmail`
 Gmail Pub/Sub hook setup + runner. See [/automation/gmail-pubsub](/automation/gmail-pubsub).

@@ -415,9 +391,6 @@ Options:
 - `--ws-log <auto|full|compact>`
 - `--compact` (alias for `--ws-log compact`)

-### `gateway-daemon`
-Run the Gateway as a long-lived daemon (same options as `gateway`, minus `--allow-unconfigured` and `--force`).
-
 ### `daemon`
 Manage the Gateway service (launchd/systemd/schtasks).

@@ -435,7 +408,6 @@ Notes:
 - `daemon status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans).
 - `daemon install` defaults to Node runtime; use `--runtime bun` only when WhatsApp is disabled.
 - `daemon install` options: `--port`, `--runtime`, `--token`.
- `gateway install|uninstall|start|stop|restart` remain as service aliases; `daemon` is the dedicated manager.

 ### `gateway <subcommand>`
 Gateway RPC helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for each).
@@ -444,15 +416,6 @@ Subcommands:
 - `gateway call <method> [--params <json>]`
 - `gateway health`
 - `gateway status`
- `gateway wake --text <text> [--mode now|next-heartbeat]`
- `gateway send --to <jidOrPhone> --message <text> [--media-url <url>] [--gif-playback] [--idempotency-key <key>]`
- `gateway agent --message <text> [--to <jidOrPhone>] [--session-id <id>] [--thinking <level>] [--deliver] [--timeout-seconds <n>] [--idempotency-key <key>]`
- `gateway install`
- `gateway uninstall`
- `gateway start`
- `gateway stop`
- `gateway restart`
- `gateway daemon status` (alias for `clawdbot daemon status`)

 Common RPCs:
 - `config.apply` (validate + write config + restart + wake)
@@ -573,27 +536,17 @@ Camera:

 Canvas + screen:
 - `nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]`
+- `nodes canvas present --node <id|name|ip> [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>] [--invoke-timeout <ms>]`
+- `nodes canvas hide --node <id|name|ip> [--invoke-timeout <ms>]`
+- `nodes canvas navigate <url> --node <id|name|ip> [--invoke-timeout <ms>]`
+- `nodes canvas eval [<js>] --node <id|name|ip> [--js <code>] [--invoke-timeout <ms>]`
+- `nodes canvas a2ui push --node <id|name|ip> (--jsonl <path> | --text <text>) [--invoke-timeout <ms>]`
+- `nodes canvas a2ui reset --node <id|name|ip> [--invoke-timeout <ms>]`
 - `nodes screen record --node <id|name|ip> [--screen <index>] [--duration <ms|10s>] [--fps <n>] [--no-audio] [--out <path>] [--invoke-timeout <ms>]`

 Location:
 - `nodes location get --node <id|name|ip> [--max-age <ms>] [--accuracy <coarse|balanced|precise>] [--location-timeout <ms>] [--invoke-timeout <ms>]`

-## Canvas
-
-Canvas RPC helper (top-level wrapper for `node.invoke`). See [/platforms/mac/canvas](/platforms/mac/canvas).
-
-Common options:
- `--url`, `--token`, `--timeout`, `--json`
-
-Subcommands:
- `canvas snapshot [--node <id|name|ip>] [--format png|jpg] [--max-width <px>] [--quality <0-1>]`
- `canvas present [--node <id|name|ip>] [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>]`
- `canvas hide [--node <id|name|ip>]`
- `canvas navigate <url> [--node <id|name|ip>]`
- `canvas eval [<js>] [--js <code>] [--node <id|name|ip>]`
- `canvas a2ui push (--jsonl <path> | --text <text>) [--node <id|name|ip>]`
- `canvas a2ui reset [--node <id|name|ip>]`
-
 ## Browser

 Browser control CLI (dedicated Chrome/Chromium). See [/tools/browser](/tools/browser).
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -167,7 +167,7 @@ If set, CLAWDBOT derives defaults (only when you haven’t set them explicitly):

 ### `wizard`

-Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`).
+Metadata written by CLI wizards (`onboard`, `configure`, `doctor`).

 ```json5
 {
--- a/docs/gateway/index.md
+++ b/docs/gateway/index.md
@@ -172,15 +172,13 @@ Notes:
 - `daemon status` probes the Gateway RPC by default (same URL/token defaults as `gateway status`).
 - `daemon status --deep` adds system-level scans (LaunchDaemons/system units).
 - `daemon status` now reports runtime state (PID/exit status) and port collisions when the gateway isn’t reachable.
- `gateway install|uninstall|start|stop|restart` remain supported as aliases; `daemon` is the dedicated manager.
- `gateway daemon status` is an alias for `clawdbot daemon status`.
 - If other gateway-like services are detected, the CLI warns. We recommend **one gateway per machine**; one gateway can host multiple agents.
  - Cleanup: `clawdbot daemon uninstall` (current service) and `clawdbot doctor` (legacy migrations).

 Bundled mac app:
 - Clawdbot.app can bundle a bun-compiled gateway binary and install a per-user LaunchAgent labeled `com.clawdbot.gateway`.
- To stop it cleanly, use `clawdbot gateway stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).
- To restart, use `clawdbot gateway restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`).
+- To stop it cleanly, use `clawdbot daemon stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).
+- To restart, use `clawdbot daemon restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`).

 ## Supervision (systemd user unit)
 Create `~/.config/systemd/user/clawdbot-gateway.service`:
@@ -236,10 +234,10 @@ Windows installs should use **WSL2** and follow the Linux systemd section above.

 ## CLI helpers
 - `clawdbot gateway health|status` — request health/status over the Gateway WS.
- `clawdbot gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
- `clawdbot gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
+- `clawdbot send --to <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
+- `clawdbot agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
 - `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
+- `clawdbot daemon stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
 - Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.

 ## Migration guidance
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -202,7 +202,7 @@ kill -9 <PID>
 If the gateway is supervised by launchd, killing the PID will just respawn it.
 Stop the supervisor instead:
 ```bash
-clawdbot gateway stop
+clawdbot daemon stop
 # Or: launchctl bootout gui/$UID/com.clawdbot.gateway
 ```

--- a/docs/install/updating.md
+++ b/docs/install/updating.md
@@ -34,12 +34,12 @@ Then:

 ```bash
 clawdbot doctor
-clawdbot gateway restart
+clawdbot daemon restart
 clawdbot health
 ```

 Notes:
- If your Gateway runs as a service, `clawdbot gateway restart` is preferred over killing PIDs.
+- If your Gateway runs as a service, `clawdbot daemon restart` is preferred over killing PIDs.
 - If you’re pinned to a specific version, see “Rollback / pinning” below.

 ## Update (Control UI / RPC)
@@ -87,8 +87,8 @@ Details: [Doctor](/gateway/doctor)
 CLI (works regardless of OS):

 ```bash
-clawdbot gateway stop
-clawdbot gateway restart
+clawdbot daemon stop
+clawdbot daemon restart
 clawdbot gateway --port 18789
 ```

@@ -113,7 +113,7 @@ Then restart + re-run doctor:

 ```bash
 clawdbot doctor
-clawdbot gateway restart
+clawdbot daemon restart
 ```

 ### Pin (source) by date
@@ -130,7 +130,7 @@ Then reinstall deps + restart:
 ```bash
 pnpm install
 pnpm build
-clawdbot gateway restart
+clawdbot daemon restart
 ```

 If you want to go back to latest later:
--- a/docs/nodes/index.md
+++ b/docs/nodes/index.md
@@ -51,13 +51,6 @@ clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format png
 clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
 ```

-Simple shortcut (auto-picks a single connected node if possible):
-
-```bash
-clawdbot canvas snapshot --format png
-clawdbot canvas snapshot --format jpg --max-width 1200 --quality 0.9
-```
-
 ## Photos + videos (node camera)

 Photos (`jpg`):
--- a/docs/platforms/exe-dev.md
+++ b/docs/platforms/exe-dev.md
@@ -167,7 +167,7 @@ More: [Linux](/platforms/linux)
 ```bash
 npm i -g clawdbot@latest
 clawdbot doctor
-clawdbot gateway restart
+clawdbot daemon restart
 clawdbot health
 ```

--- a/docs/platforms/index.md
+++ b/docs/platforms/index.md
@@ -31,7 +31,7 @@ Linux companion apps are planned, but the core Gateway is fully supported today.
 Use one of these (all supported):

 - Wizard (recommended): `clawdbot onboard --install-daemon`
- Direct: `clawdbot daemon install` (alias: `clawdbot gateway install`)
+- Direct: `clawdbot daemon install`
 - Configure flow: `clawdbot configure` → select **Gateway daemon**
 - Repair/migrate: `clawdbot doctor` (offers to install or fix the service)

--- a/docs/platforms/linux.md
+++ b/docs/platforms/linux.md
@@ -36,7 +36,7 @@ clawdbot daemon install
 Or:

 ```
-clawdbot gateway install
+clawdbot daemon install
 ```

 Or:
--- a/docs/platforms/mac/bun.md
+++ b/docs/platforms/mac/bun.md
@@ -18,7 +18,7 @@ App bundle layout:
  - bun `--compile` relay executable built from [`dist/macos/relay.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/macos/relay.js)
  - Supports:
    - `clawdbot …` (CLI)
-    - `clawdbot gateway-daemon …` (LaunchAgent daemon)
+    - `clawdbot gateway …` (LaunchAgent daemon)
 - `Clawdbot.app/Contents/Resources/Relay/package.json`
  - tiny “p runtime compatibility” file (see below)
 - `Clawdbot.app/Contents/Resources/Relay/theme/`
@@ -109,7 +109,7 @@ dist/Clawdbot.app/Contents/Resources/Relay/clawdbot --version

 CLAWDBOT_SKIP_PROVIDERS=1 \
 CLAWDBOT_SKIP_CANVAS_HOST=1 \
-dist/Clawdbot.app/Contents/Resources/Relay/clawdbot gateway-daemon --port 18999 --bind loopback
+dist/Clawdbot.app/Contents/Resources/Relay/clawdbot gateway --port 18999 --bind loopback
 ```

 Then, in another shell:
--- a/docs/platforms/mac/canvas.md
+++ b/docs/platforms/mac/canvas.md
@@ -87,12 +87,12 @@ Related:

 Use the main `clawdbot` CLI; it invokes canvas commands via `node.invoke`.

- `clawdbot canvas present [--node <id>] [--target <...>] [--x/--y/--width/--height]`
+- `clawdbot nodes canvas present --node <id> [--target <...>] [--x/--y/--width/--height]`
  - Local targets map into the session directory via the custom scheme (directory targets resolve `index.html|index.htm`).
  - If `/` has no index file, Canvas shows the built-in scaffold page and returns `status: "welcome"`.
- `clawdbot canvas hide [--node <id>]`
- `clawdbot canvas eval --js <code> [--node <id>]`
- `clawdbot canvas snapshot [--node <id>]`
+- `clawdbot nodes canvas hide --node <id>`
+- `clawdbot nodes canvas eval --js <code> --node <id>`
+- `clawdbot nodes canvas snapshot --node <id>`

 ### Canvas A2UI

@@ -104,8 +104,8 @@ http://<gateway-host>:18793/__clawdbot__/a2ui/

 The macOS app simply renders that page in the Canvas panel. The agent can drive it with JSONL **server→client protocol messages** (one JSON object per line):

- `clawdbot canvas a2ui push --jsonl <path> [--node <id>]`
- `clawdbot canvas a2ui reset [--node <id>]`
+- `clawdbot nodes canvas a2ui push --jsonl <path> --node <id>`
+- `clawdbot nodes canvas a2ui reset --node <id>`

 `push` expects a JSONL file where **each line is a single JSON object** (parsed and forwarded to the in-page A2UI renderer).

@@ -113,18 +113,18 @@ Minimal example (v0.8):

 ```bash
 cat > /tmp/a2ui-v0.8.jsonl <<'EOF'
-{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, `canvas a2ui push` works."},"usageHint":"body"}}}]}}
+{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, `nodes canvas a2ui push` works."},"usageHint":"body"}}}]}}
 {"beginRendering":{"surfaceId":"main","root":"root"}}
 EOF

-clawdbot canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
+clawdbot nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
 ```

 Notes:
 - This does **not** support the A2UI v0.9 examples using `createSurface`.
 - A2UI **fails** if the Gateway canvas host is unreachable (no local fallback).
- `canvas a2ui push` validates JSONL (line numbers on errors) and rejects v0.9 payloads.
- Quick smoke: `clawdbot canvas a2ui push --text "Hello from A2UI"` renders a minimal v0.8 view.
+- `nodes canvas a2ui push` validates JSONL (line numbers on errors) and rejects v0.9 payloads.
+- Quick smoke: `clawdbot nodes canvas a2ui push --node <id> --text "Hello from A2UI"` renders a minimal v0.8 view.

 ## Triggering agent runs from Canvas (deep links)

--- a/docs/platforms/macos.md
+++ b/docs/platforms/macos.md
@@ -40,7 +40,7 @@ Details: [Gateway runbook](/gateway) and [Bundled bun Gateway](/platforms/mac/bu
  - `Clawdbot` (LSUIElement MenuBarExtra app; hosts Gateway + node bridge + PeekabooBridgeHost).
 - Bundle ID: `com.clawdbot.mac`.
 - Bundled runtime binaries live under `Contents/Resources/Relay/`:
-  - `clawdbot` (bun‑compiled relay: CLI + gateway-daemon)
+  - `clawdbot` (bun‑compiled relay: CLI + gateway)
 - The app symlinks `clawdbot` into `/usr/local/bin` and `/opt/homebrew/bin`.

 ## Gateway + node bridge
@@ -65,7 +65,7 @@ Details: [Gateway runbook](/gateway) and [Bundled bun Gateway](/platforms/mac/bu
 ## CLI (`clawdbot`)
 - The **only** CLI is `clawdbot` (TS/bun). There is no `clawdbot-mac` helper.
 - For mac‑specific actions, the CLI uses `node.invoke`:
-  - `clawdbot canvas present|navigate|eval|snapshot|a2ui push|a2ui reset`
+  - `clawdbot nodes canvas present|navigate|eval|snapshot|a2ui push|a2ui reset`
  - `clawdbot nodes run --node <id> -- <command...>`
  - `clawdbot nodes notify --node <id> --title ...`

--- a/docs/platforms/windows.md
+++ b/docs/platforms/windows.md
@@ -37,7 +37,7 @@ clawdbot daemon install
 Or:

 ```
-clawdbot gateway install
+clawdbot daemon install
 ```

 Or:
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -100,7 +100,7 @@ Notes:
 - Uses gateway `node.invoke` under the hood.
 - If no `node` is provided, the tool picks a default (single connected node or local mac node).
 - A2UI is v0.8 only (no `createSurface`); the CLI rejects v0.9 JSONL with line errors.
- Quick smoke: `clawdbot canvas a2ui push --text "Hello from A2UI"`.
+- Quick smoke: `clawdbot nodes canvas a2ui push --node <id> --text "Hello from A2UI"`.

 ### `nodes`
 Discover and target paired nodes; send notifications; capture camera/screen.
@@ -162,7 +162,7 @@ Notes:
 Restart or apply updates to the running Gateway process (in-place).

 Core actions:
- `restart` (sends `SIGUSR1` to the current process; `clawdbot gateway`/`gateway-daemon` restart in-place)
+- `restart` (sends `SIGUSR1` to the current process; `clawdbot gateway` restart in-place)
 - `config.get` / `config.schema`
 - `config.apply` (validate + write config + restart + wake)
 - `update.run` (run update + restart + wake)