clawdbot/docs/refactor/cli-unification.md

summary, read_when

summary	read_when
Refactor: unify on the clawdbot CLI + gateway-first control; retire clawdbot-mac	Removing or replacing the macOS CLI helper Adding node capabilities or permissions metadata Updating macOS app packaging/install flows

CLI unification (clawdbot-only)

Status: active refactor · Date: 2025-12-20

Goals

• Single CLI: use clawdbot for all automation (local + remote). Retire clawdbot-mac.
• Gateway-first: all agent actions flow through the Gateway WebSocket + node.invoke.
• Permission awareness: nodes advertise permission state so the agent can decide what to run.
• No duplicate paths: remove macOS control socket + Swift CLI surface.

Non-goals

• Keep legacy clawdbot-mac compatibility.
• Support agent control when no Gateway is running.

Key decisions

1. No Gateway → no control

   • If the macOS app is running but the Gateway is not, remote commands (canvas/run/notify) are unavailable.
   • This is acceptable to keep one network surface.

2. Remove ensure-permissions CLI

   • Permissions are advertised by the node (e.g., screen recording granted/denied).
   • Commands will still fail with explicit errors when permissions are missing.

3. Mac app installs/symlinks clawdbot

   • Bundle a standalone clawdbot binary in the app (bun-compiled).
   • Install/symlink that binary to /usr/local/bin/clawdbot and /opt/homebrew/bin/clawdbot.
   • No clawdbot-mac helper remains.

4. Canvas parity across node types

   • Use node.invoke commands consistently (canvas.present|navigate|eval|snapshot|a2ui.*).
   • The TS CLI provides convenient wrappers so agents never have to craft raw node.invoke calls.

Command surface (new/normalized)

• clawdbot nodes invoke --command canvas.* remains valid.
• New CLI wrappers for convenience:
  • clawdbot canvas present|navigate|eval|snapshot|a2ui push|a2ui reset
• New node commands (mac-only initially):
  • system.run (shell execution)
  • system.notify (local notifications)

Permission advertising

• Node hello/pairing includes a permissions map:
  • Example keys: screenRecording, accessibility, microphone, notifications, speechRecognition.
  • Values: boolean (true = granted, false = not granted).
• Gateway node.list / node.describe surfaces the map.

Gateway mode + config

• Gateways should only auto-start when explicitly configured for local mode.
• When config is missing or explicitly remote, clawdbot gateway should refuse to auto-start unless forced.

Implementation checklist

• Add bun-compiled clawdbot binary to macOS app bundle; update codesign + install flows.
• Remove ClawdbotCLI target and control socket server.
• Add node command(s) for system.run and system.notify on macOS.
• Add permission map to node hello/pairing + gateway responses.
• Update TS CLI + docs to use clawdbot only.