feat: add logs cli and restart hints

docs/cli/index.md

@@ -423,6 +423,15 @@ Notes:
 - `daemon install` defaults to Node runtime; use `--runtime bun` only when WhatsApp is disabled.
 - `daemon install` options: `--port`, `--runtime`, `--token`.
 
+### `logs`
+Tail Gateway file logs via RPC.
+
+Examples:
+```bash
+clawdbot logs --follow
+clawdbot logs --limit 200
+```
+
 ### `gateway <subcommand>`
 Gateway RPC helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for each).
 

docs/gateway/index.md

@@ -166,12 +166,14 @@ clawdbot daemon status
 clawdbot daemon install
 clawdbot daemon stop
 clawdbot daemon restart
+clawdbot logs --follow
 ```
 
 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.
+- `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed).
 - 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).
 
@@ -179,6 +181,7 @@ 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 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`).
+  - `launchctl` only works if the LaunchAgent is installed; otherwise use `clawdbot daemon install` first.
 
 ## Supervision (systemd user unit)
 Create `~/.config/systemd/user/clawdbot-gateway.service`:

docs/gateway/logging.md

@@ -24,6 +24,11 @@ Clawdbot uses a file logger backed by `tslog` ([`src/logging.ts`](https://github
 The file format is one JSON object per line.
 
 The Control UI Logs tab tails this file via the gateway (`logs.tail`).
+CLI can do the same:
+
+```bash
+clawdbot logs --follow
+```
 
 **Verbose vs. log levels**
 

docs/gateway/troubleshooting.md

@@ -23,8 +23,10 @@ clawdbot doctor
 Doctor/daemon will show runtime state (PID/last exit) and log hints.
 
 **Logs:**
-- macOS: `~/.clawdbot/logs/gateway.log` and `gateway.err.log`
-- Linux: `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`
+- Preferred: `clawdbot logs --follow`
+- File logs (always): `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or your configured `logging.file`)
+- macOS LaunchAgent (if installed): `~/.clawdbot/logs/gateway.log` and `gateway.err.log`
+- Linux systemd (if installed): `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`
 - Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST`
 
 ### Address Already in Use (Port 18789)
@@ -74,6 +76,8 @@ cat ~/.clawdbot/clawdbot.json | jq '.routing.groupChat, .whatsapp.groups, .teleg
 
 **Check 3:** Check the logs
 ```bash
+clawdbot logs --follow
+# or if you want quick filters:
 tail -f "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"
 ```
 
@@ -126,7 +130,7 @@ clawdbot status
 clawdbot status --deep
 
 # View recent connection events
-tail -100 /tmp/clawdbot/clawdbot-*.log | grep "connection\\|disconnect\\|logout"
+clawdbot logs --limit 200 | grep "connection\\|disconnect\\|logout"
 ```
 
 **Fix:** Usually reconnects automatically once the Gateway is running. If you’re stuck, restart the Gateway process (however you supervise it), or run it manually with verbose output:

docs/install/updating.md

@@ -90,12 +90,14 @@ CLI (works regardless of OS):
 clawdbot daemon stop
 clawdbot daemon restart
 clawdbot gateway --port 18789
+clawdbot logs --follow
 ```
 
 If you’re supervised:
 - macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`
 - Linux systemd user service: `systemctl --user restart clawdbot-gateway.service`
 - Windows (WSL2): `systemctl --user restart clawdbot-gateway.service`
+  - `launchctl`/`systemctl` only work if the service is installed; otherwise run `clawdbot daemon install`.
 
 Runbook + exact service labels: [Gateway runbook](/gateway)
 

docs/platforms/macos.md

@@ -23,6 +23,8 @@ launchctl kickstart -k gui/$UID/com.clawdbot.gateway
 launchctl bootout gui/$UID/com.clawdbot.gateway
 ```
 
+`launchctl` only works if the LaunchAgent is installed; otherwise run `clawdbot daemon install` first.
+
 Details: [Gateway runbook](/gateway) and [Bundled bun Gateway](/platforms/mac/bun).
 
 ## Purpose

docs/providers/telegram.md

@@ -208,7 +208,7 @@ Outbound Telegram API calls retry on transient network/429 errors with exponenti
 - If `telegram.groups` is set, the group must be listed or use `"*"`
 - Check Privacy Settings in @BotFather → "Group Privacy" should be **OFF**
 - Verify bot is actually a member (not just an admin with no read access)
-- Check gateway logs: `journalctl --user -u clawdbot -f` (look for "skipping group message")
+- Check gateway logs: `clawdbot logs --follow` (look for "skipping group message")
 
 **Bot responds to mentions but not `/activation always`:**
 - The `/activation` command updates session state but doesn't persist to config

docs/start/faq.md

@@ -363,6 +363,12 @@ Default log file:
 
 You can set a stable path via `logging.file`. File log level is controlled by `logging.level`. Console verbosity is controlled by `--verbose` and `logging.consoleLevel`.
 
+Fastest log tail:
+
+```bash
+clawdbot logs --follow
+```
+
 ### What’s the fastest way to get more details when something fails?
 
 Start the Gateway with `--verbose` to get more console detail. Then inspect the log file for provider auth, model routing, and RPC errors.