534 lines
13 KiB
Markdown
534 lines
13 KiB
Markdown
---
|
|
summary: "CLI reference for clawdbot commands, subcommands, and options"
|
|
read_when:
|
|
- Adding or modifying CLI commands or options
|
|
- Documenting new command surfaces
|
|
---
|
|
|
|
# CLI reference
|
|
|
|
This page mirrors `src/cli/*` and is the source of truth for CLI behavior.
|
|
If you change the CLI code, update this doc.
|
|
|
|
## Global flags
|
|
|
|
- `--dev`: isolate state under `~/.clawdbot-dev` and shift default ports.
|
|
- `--profile <name>`: isolate state under `~/.clawdbot-<name>`.
|
|
- `-V`, `--version`, `-v`: print version and exit.
|
|
|
|
## Command tree
|
|
|
|
```
|
|
clawdbot [--dev] [--profile <name>] <command>
|
|
setup
|
|
onboard
|
|
configure (alias: config)
|
|
update
|
|
doctor
|
|
login
|
|
logout
|
|
send
|
|
poll
|
|
agent
|
|
status
|
|
health
|
|
sessions
|
|
gateway
|
|
call
|
|
health
|
|
status
|
|
wake
|
|
send
|
|
agent
|
|
stop
|
|
restart
|
|
gateway-daemon
|
|
models
|
|
list
|
|
status
|
|
set
|
|
set-image
|
|
aliases list|add|remove
|
|
fallbacks list|add|remove|clear
|
|
image-fallbacks list|add|remove|clear
|
|
scan
|
|
wake
|
|
cron
|
|
status
|
|
list
|
|
add
|
|
edit
|
|
rm
|
|
enable
|
|
disable
|
|
runs
|
|
run
|
|
nodes
|
|
status
|
|
describe
|
|
list
|
|
pending
|
|
approve
|
|
reject
|
|
rename
|
|
invoke
|
|
run
|
|
notify
|
|
camera list|snap|clip
|
|
canvas snapshot
|
|
screen record
|
|
location get
|
|
canvas
|
|
snapshot
|
|
present
|
|
hide
|
|
navigate
|
|
eval
|
|
a2ui push|reset
|
|
browser
|
|
status
|
|
start
|
|
stop
|
|
reset-profile
|
|
tabs
|
|
open
|
|
focus
|
|
close
|
|
profiles
|
|
create-profile
|
|
delete-profile
|
|
screenshot
|
|
snapshot
|
|
navigate
|
|
resize
|
|
click
|
|
type
|
|
press
|
|
hover
|
|
drag
|
|
select
|
|
upload
|
|
fill
|
|
dialog
|
|
wait
|
|
evaluate
|
|
console
|
|
pdf
|
|
hooks
|
|
gmail setup|run
|
|
pairing
|
|
list
|
|
approve
|
|
telegram
|
|
pairing list|approve
|
|
docs
|
|
dns
|
|
setup
|
|
tui
|
|
```
|
|
|
|
## Setup + onboarding
|
|
|
|
### `setup`
|
|
Initialize config + workspace.
|
|
|
|
Options:
|
|
- `--workspace <dir>`: agent workspace path (default `~/clawd`).
|
|
- `--wizard`: run the onboarding wizard.
|
|
- `--non-interactive`: run wizard without prompts.
|
|
- `--mode <local|remote>`: wizard mode.
|
|
- `--remote-url <url>`: remote Gateway URL.
|
|
- `--remote-token <token>`: remote Gateway token.
|
|
|
|
### `onboard`
|
|
Interactive wizard to set up gateway, workspace, and skills.
|
|
|
|
Options:
|
|
- `--workspace <dir>`
|
|
- `--non-interactive`
|
|
- `--mode <local|remote>`
|
|
- `--auth-choice <oauth|apiKey|minimax|skip>`
|
|
- `--anthropic-api-key <key>`
|
|
- `--gateway-port <port>`
|
|
- `--gateway-bind <loopback|lan|tailnet|auto>`
|
|
- `--gateway-auth <off|token|password>`
|
|
- `--gateway-token <token>`
|
|
- `--gateway-password <password>`
|
|
- `--remote-url <url>`
|
|
- `--remote-token <token>`
|
|
- `--tailscale <off|serve|funnel>`
|
|
- `--tailscale-reset-on-exit`
|
|
- `--install-daemon`
|
|
- `--daemon-runtime <node|bun>`
|
|
- `--skip-skills`
|
|
- `--skip-health`
|
|
- `--node-manager <npm|pnpm|bun>`
|
|
- `--json`
|
|
|
|
### `configure` / `config`
|
|
Interactive configuration wizard (models, providers, skills, gateway).
|
|
|
|
### `update`
|
|
Audit and modernize the local configuration.
|
|
|
|
### `doctor`
|
|
Health checks + quick fixes.
|
|
|
|
Options:
|
|
- `--no-workspace-suggestions`: disable workspace memory hints.
|
|
|
|
## Auth + provider helpers
|
|
|
|
### `login`
|
|
Link a WhatsApp Web account via QR.
|
|
|
|
Options:
|
|
- `--verbose`
|
|
- `--provider <provider>` (default `whatsapp`)
|
|
- `--account <id>`
|
|
|
|
### `logout`
|
|
Clear cached WhatsApp Web credentials.
|
|
|
|
Options:
|
|
- `--provider <provider>`
|
|
- `--account <id>`
|
|
|
|
### `pairing`
|
|
Approve DM pairing requests across providers.
|
|
|
|
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).
|
|
|
|
Subcommands:
|
|
- `hooks gmail setup` (requires `--account <email>`; supports `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--push-endpoint`, `--json`)
|
|
- `hooks gmail run` (runtime overrides for the same flags)
|
|
|
|
### `dns setup`
|
|
Wide-area discovery DNS helper (CoreDNS + Tailscale). See [/gateway/discovery](/gateway/discovery).
|
|
|
|
Options:
|
|
- `--apply`: install/update CoreDNS config (requires sudo; macOS only).
|
|
|
|
## Messaging + agent
|
|
|
|
### `send`
|
|
Send a message through a provider.
|
|
|
|
Required:
|
|
- `--to <dest>`
|
|
- `--message <text>`
|
|
|
|
Options:
|
|
- `--media <path-or-url>`
|
|
- `--gif-playback`
|
|
- `--provider <whatsapp|telegram|discord|slack|signal|imessage>`
|
|
- `--account <id>` (WhatsApp)
|
|
- `--dry-run`
|
|
- `--json`
|
|
- `--verbose`
|
|
|
|
### `poll`
|
|
Create a poll (WhatsApp or Discord).
|
|
|
|
Required:
|
|
- `--to <id>`
|
|
- `--question <text>`
|
|
- `--option <choice>` (repeat 2-12 times)
|
|
|
|
Options:
|
|
- `--max-selections <n>`
|
|
- `--duration-hours <n>` (Discord)
|
|
- `--provider <whatsapp|discord>`
|
|
- `--dry-run`
|
|
- `--json`
|
|
- `--verbose`
|
|
|
|
### `agent`
|
|
Run one agent turn via the Gateway (or `--local` embedded).
|
|
|
|
Required:
|
|
- `--message <text>`
|
|
|
|
Options:
|
|
- `--to <dest>` (for session key and optional delivery)
|
|
- `--session-id <id>`
|
|
- `--thinking <off|minimal|low|medium|high>`
|
|
- `--verbose <on|off>`
|
|
- `--provider <whatsapp|telegram|discord|slack|signal|imessage>`
|
|
- `--local`
|
|
- `--deliver`
|
|
- `--json`
|
|
- `--timeout <seconds>`
|
|
|
|
### `status`
|
|
Show linked session health and recent recipients.
|
|
|
|
Options:
|
|
- `--json`
|
|
- `--deep` (probe providers)
|
|
- `--timeout <ms>`
|
|
- `--verbose`
|
|
|
|
### `health`
|
|
Fetch health from the running Gateway.
|
|
|
|
Options:
|
|
- `--json`
|
|
- `--timeout <ms>`
|
|
- `--verbose`
|
|
|
|
### `sessions`
|
|
List stored conversation sessions.
|
|
|
|
Options:
|
|
- `--json`
|
|
- `--verbose`
|
|
- `--store <path>`
|
|
- `--active <minutes>`
|
|
|
|
## Gateway
|
|
|
|
### `gateway`
|
|
Run the WebSocket Gateway.
|
|
|
|
Options:
|
|
- `--port <port>`
|
|
- `--bind <loopback|tailnet|lan|auto>`
|
|
- `--token <token>`
|
|
- `--auth <token|password>`
|
|
- `--password <password>`
|
|
- `--tailscale <off|serve|funnel>`
|
|
- `--tailscale-reset-on-exit`
|
|
- `--allow-unconfigured`
|
|
- `--force` (kill existing listener on port)
|
|
- `--verbose`
|
|
- `--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`).
|
|
|
|
### `gateway <subcommand>`
|
|
Gateway RPC helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for each).
|
|
|
|
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 stop`
|
|
- `gateway restart`
|
|
|
|
## Models
|
|
|
|
See [/concepts/models](/concepts/models) for fallback behavior and scanning strategy.
|
|
|
|
### `models` (root)
|
|
`clawdbot models` is an alias for `models status`.
|
|
|
|
### `models list`
|
|
Options:
|
|
- `--all`
|
|
- `--local`
|
|
- `--provider <name>`
|
|
- `--json`
|
|
- `--plain`
|
|
|
|
### `models status`
|
|
Options:
|
|
- `--json`
|
|
- `--plain`
|
|
|
|
### `models set <model>`
|
|
Set `agent.model.primary`.
|
|
|
|
### `models set-image <model>`
|
|
Set `agent.imageModel.primary`.
|
|
|
|
### `models aliases list|add|remove`
|
|
Options:
|
|
- `list`: `--json`, `--plain`
|
|
- `add <alias> <model>`
|
|
- `remove <alias>`
|
|
|
|
### `models fallbacks list|add|remove|clear`
|
|
Options:
|
|
- `list`: `--json`, `--plain`
|
|
- `add <model>`
|
|
- `remove <model>`
|
|
- `clear`
|
|
|
|
### `models image-fallbacks list|add|remove|clear`
|
|
Options:
|
|
- `list`: `--json`, `--plain`
|
|
- `add <model>`
|
|
- `remove <model>`
|
|
- `clear`
|
|
|
|
### `models scan`
|
|
Options:
|
|
- `--min-params <b>`
|
|
- `--max-age-days <days>`
|
|
- `--provider <name>`
|
|
- `--max-candidates <n>`
|
|
- `--timeout <ms>`
|
|
- `--concurrency <n>`
|
|
- `--yes`
|
|
- `--no-input`
|
|
- `--set-default`
|
|
- `--set-image`
|
|
- `--json`
|
|
|
|
## Cron + wake
|
|
|
|
### `wake`
|
|
Enqueue a system event and optionally trigger a heartbeat (Gateway RPC).
|
|
|
|
Required:
|
|
- `--text <text>`
|
|
|
|
Options:
|
|
- `--mode <now|next-heartbeat>`
|
|
- `--json`
|
|
- `--url`, `--token`, `--timeout`, `--expect-final`
|
|
|
|
### `cron`
|
|
Manage scheduled jobs (Gateway RPC). See [/automation/cron-jobs](/automation/cron-jobs).
|
|
|
|
Subcommands:
|
|
- `cron status [--json]`
|
|
- `cron list [--all] [--json]`
|
|
- `cron add` (requires `--name` and exactly one of `--at` | `--every` | `--cron`, and exactly one payload of `--system-event` | `--message`)
|
|
- `cron edit <id>` (patch fields)
|
|
- `cron rm <id>`
|
|
- `cron enable <id>`
|
|
- `cron disable <id>`
|
|
- `cron runs --id <id> [--limit <n>]`
|
|
- `cron run <id> [--force]`
|
|
|
|
All `cron` commands accept `--url`, `--token`, `--timeout`, `--expect-final`.
|
|
|
|
## Nodes
|
|
|
|
`nodes` talks to the Gateway and targets paired nodes. See [/nodes](/nodes).
|
|
|
|
Common options:
|
|
- `--url`, `--token`, `--timeout`, `--json`
|
|
|
|
Subcommands:
|
|
- `nodes status`
|
|
- `nodes describe --node <id|name|ip>`
|
|
- `nodes list`
|
|
- `nodes pending`
|
|
- `nodes approve <requestId>`
|
|
- `nodes reject <requestId>`
|
|
- `nodes rename --node <id|name|ip> --name <displayName>`
|
|
- `nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]`
|
|
- `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>` (mac only)
|
|
- `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]` (mac only)
|
|
|
|
Camera:
|
|
- `nodes camera list --node <id|name|ip>`
|
|
- `nodes camera snap --node <id|name|ip> [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]`
|
|
- `nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]`
|
|
|
|
Canvas + screen:
|
|
- `nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--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).
|
|
|
|
Common options:
|
|
- `--url <controlUrl>`
|
|
- `--browser-profile <name>`
|
|
- `--json`
|
|
|
|
Manage:
|
|
- `browser status`
|
|
- `browser start`
|
|
- `browser stop`
|
|
- `browser reset-profile`
|
|
- `browser tabs`
|
|
- `browser open <url>`
|
|
- `browser focus <targetId>`
|
|
- `browser close [targetId]`
|
|
- `browser profiles`
|
|
- `browser create-profile --name <name> [--color <hex>] [--cdp-url <url>]`
|
|
- `browser delete-profile --name <name>`
|
|
|
|
Inspect:
|
|
- `browser screenshot [targetId] [--full-page] [--ref <ref>] [--element <selector>] [--type png|jpeg]`
|
|
- `browser snapshot [--format aria|ai] [--target-id <id>] [--limit <n>] [--out <path>]`
|
|
|
|
Actions:
|
|
- `browser navigate <url> [--target-id <id>]`
|
|
- `browser resize <width> <height> [--target-id <id>]`
|
|
- `browser click <ref> [--double] [--button <left|right|middle>] [--modifiers <csv>] [--target-id <id>]`
|
|
- `browser type <ref> <text> [--submit] [--slowly] [--target-id <id>]`
|
|
- `browser press <key> [--target-id <id>]`
|
|
- `browser hover <ref> [--target-id <id>]`
|
|
- `browser drag <startRef> <endRef> [--target-id <id>]`
|
|
- `browser select <ref> <values...> [--target-id <id>]`
|
|
- `browser upload <paths...> [--ref <ref>] [--input-ref <ref>] [--element <selector>] [--target-id <id>] [--timeout-ms <ms>]`
|
|
- `browser fill [--fields <json>] [--fields-file <path>] [--target-id <id>]`
|
|
- `browser dialog --accept|--dismiss [--prompt <text>] [--target-id <id>] [--timeout-ms <ms>]`
|
|
- `browser wait [--time <ms>] [--text <value>] [--text-gone <value>] [--target-id <id>]`
|
|
- `browser evaluate --fn <code> [--ref <ref>] [--target-id <id>]`
|
|
- `browser console [--level <error|warn|info>] [--target-id <id>]`
|
|
- `browser pdf [--target-id <id>]`
|
|
|
|
## Docs search
|
|
|
|
### `docs [query...]`
|
|
Search the live docs index.
|
|
|
|
## TUI
|
|
|
|
### `tui`
|
|
Open the terminal UI connected to the Gateway.
|
|
|
|
Options:
|
|
- `--url <url>`
|
|
- `--token <token>`
|
|
- `--password <password>`
|
|
- `--session <key>`
|
|
- `--deliver`
|
|
- `--thinking <level>`
|
|
- `--timeout-ms <ms>`
|
|
- `--history-limit <n>`
|