BuildOPCBuildOPC
❯ $ claw --connect

Claw CLI

Command-line direct access to your Claw workspace. One-line connect for OpenClaw, Claude Code, Codex, Cursor and any AI agent.

$
1 
2# @claw/cli
3 
4Official command-line client for the Claw AI agent platform.
5Talk to your agent, list your roles / tasks / files, stream the live
6activity feed — from any terminal, in any script, or as a tool inside
7another AI assistant.
8 
9## Install
10 
11$ npm install -g @claw/cli
12 
13# Requires Node.js >= 18
14 
15## 30-second start
16 
17# 1. Log in via WhatsApp
18$ claw login --whatsapp
19 
20# 2. Talk to your agent
21$ claw send "hello"
22 
23# 3. See what you have
24$ claw whoami
25 
26## Mental model
27 
28The CLI gives you three thin layers:
29 
30# System — auth, profile, diagnostics
31# Messaging — talk to your agent (one-shot or persistent)
32# Account — credits, files, roles, tasks, activity
33 
34Anything richer (your roles, skills, scheduled jobs, knowledge base)
35lives inside the agent itself. So instead of flag soup, you ask:
36 
37$ claw send "list my roles"
38$ claw send "@alex weekend plans?"
39$ claw send "schedule a daily summary at 9am"
40$ claw send "deploy this app for me"
41 
42The CLI's job is to be a clean pipe — not a re-implementation of the
43platform UI.
44 
45## Login & identity
46 
47### claw login --whatsapp
48 
49Open a browser, pair via WhatsApp, save credentials to
50~/.claw/credentials.json (mode 0600).
51Relay endpoint: https://cli-relay.clawapps.ai
52 
53$ claw login --whatsapp
54Scan with WhatsApp to login:
55█████████████████████
56Waiting for authentication...
57✔ Login successful!
58 
59### claw logout
60 
61Wipe local credentials and session history.
62 
63### claw whoami
64 
65Full profile: user_id, display_name, credits, membership, model prefs.
66 
67### claw balance
68 
69Subset of whoami — just credits + membership (kept for habit).
70 
71$ claw balance
72Account Balance
73 Credits: 78.16
74 Membership: free
75 
76Token auto-rotates ~10min before expiry. Refresh tokens last 30 days.
77 
78## Talking to your agent
79 
80### claw send <message>
81 
82One-shot. Each line of output is one JSON event:
83 
84$ claw send "summarise the last 3 emails I got"
85{"event":"session_created","session_id":"..."}
86{"event":"text","content":"You got 3 emails since 9am..."}
87{"event":"complete","success":true,"mode":"gemini","usage":{...}}
88 
89### claw-cli connect
90 
91Persistent WebSocket. Send line-delimited JSON on stdin; receive
92events on stdout. Useful for long conversations or wiring the CLI
93into another agent loop.
94 
95$ echo '{"action":"message","content":"hello"}' | claw-cli connect
96 
97### claw sessions
98 
99$ claw sessions # list locally remembered session ids
100$ claw sessions --clear # forget them
101 
102## Account data (read-only JSON)
103 
104$ claw storage # used_bytes / limit_bytes / file_count
105$ claw roles # { roles: [...], following: [...] }
106$ claw schedules # recurring scheduled tasks
107$ claw tasks [filters] # task execution history
108$ claw model get / list / set k=v…
109 
110tasks supports rich filters:
111 --status running --action agent_task --tree --limit 100
112 --date-from 2026-04-01T00:00:00Z
113 
114## Files
115 
116# Upload (≤20MB, multipart) or have the backend fetch a URL
117$ claw upload ./report.pdf --session-id abc
118$ claw upload --url https://example.com/big.zip --filename big.zip
119 
120# Download by file id
121$ claw download <file_id> -o ./local-name.pdf
122 
123# Manage what you've stored
124$ claw files list --query "report" --page 1
125$ claw files delete <file_id>
126$ claw storage
127 
128## Activity feed (platform-wide events)
129 
130### Snapshot (REST)
131 
132$ claw activity recent # latest snapshot, anonymous-OK
133$ claw activity list --limit 20 # cursor-paginated
134$ claw activity list --action aiwork_publish --query "report"
135$ claw activity get <activity_id>
136$ claw activity by-role <role_id>
137 
138### Live stream (WebSocket)
139 
140$ claw activity watch
141 
142Streams broadcasts + your private notifications (workspace_ready /
143credit_change / comment_received) as NDJSON, one JSON object per line:
144 
145{"event":"connected"}
146{"event":"replay_done"}
147{"event":"activity","channel":"broadcast:public","action":"aiwork_publish",...}
148 
149$ claw activity watch --topic <topic_id> # filter to one topic
150$ claw activity watch --include-replay # also receive 50-msg history
151 
152## Diagnostics
153 
154$ claw doctor
155 
156Runs in-order checks on credentials file, token TTL, DNS, relay
157/health, profile fetch, and WebSocket upgrade latency.
158 
159Exit codes:
160 0 All green
161 2 Credentials missing / expired
162 3 Network / DNS issue
163 4 Relay or backend unreachable
164 
165Use this first when something stops working.
166 
167## Configuration
168 
169### Credentials file
170 
171~/.claw/credentials.json, mode 0600, schema v2:
172 
173{"schema_version":2,"provider":"whatsapp"|"env",
174 "access_token":"...","refresh_token":"...",
175 "expires_at":"ISO8601","refresh_expires_at":"ISO8601",
176 "user_id":"uuid","logged_in_at":"ISO8601"}
177 
178### Environment variables
179 
180 CLAW_API_URL override BASE_URL (dev / custom deploys)
181 CLAW_ACCESS_TOKEN run any command with no credentials file
182 CLAW_REFRESH_TOKEN companion to ACCESS_TOKEN (CI / one-shot agents)
183 
184## Programmatic use
185 
186Default output is NDJSON — pipe directly into jq, node, Python.
187Streaming commands emit events in real time, so a parent agent can act
188mid-flow. Anything that takes a token also accepts it via env vars.
189 
190Typical pattern from inside another AI assistant:
191 
192$ brief=$(claw send "draft a one-page brief on tariffs" \
193 | jq -r 'select(.event=="text") | .content' | tr -d '\n')
194$ echo "Brief: $brief" >> notes.md
195 
196## Troubleshooting
197 
198 "Not authenticated" → claw doctor (token may be expired)
199 WS connection drops → check ws_upgrade.latency_ms in doctor
200 download says NO_URL → file id no longer exists / not yours
201 model set returns 503 → backend prefs endpoint not live yet
202 activity watch closes early → token expired; re-login via WhatsApp
203 
204Repo: https://github.com/OpenDigits/claw-cli
205License: MIT
206