wacli

name	wacli
description	Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats).
homepage	https://wacli.sh
metadata	{"openclaw":{"emoji":"📱","displayName":"WhatsApp as Me","requires":{"bins":["wacli","./scripts/wacli-live.sh","./scripts/wacli-health.sh","./scripts/wacli-auth-local.sh","./scripts/wacli-send-safe.sh","./scripts/wacli-recent-reply.sh","./scripts/wacli-monitor-check.sh"]},"install":[{"id":"brew","kind":"brew","formula":"openclaw/tap/wacli","bins":["wacli"],"label":"Install wacli (brew)","versionCommand":["wacli","--version"],"versionRegex":"wacli v?(?<version>[0-9]+\\.[0-9]+\\.[0-9]+)","recommendedVersion":"0.11.1"},{"id":"go","kind":"go","module":"github.com/openclaw/wacli/cmd/wacli@v0.11.1","bins":["wacli"],"label":"Install wacli (go)","versionCommand":["wacli","--version"],"versionRegex":"wacli v?(?<version>[0-9]+\\.[0-9]+\\.[0-9]+)","recommendedVersion":"0.11.1"}]}}

wacli

Use wacli only when the user explicitly asks you to message someone else on WhatsApp, when they ask to sync/search WhatsApp history, or when you are running a scoped WhatsApp monitor/reply-check on their behalf. Do NOT use wacli for normal user chats; OpenClaw routes WhatsApp conversations automatically. If the user is chatting with you on WhatsApp, you should not reach for this tool unless they ask you to contact a third party.

Automation Rule

• For WhatsApp reply detection, scoped monitors, or "did this person reply yet?" checks, use: skills/wacli/scripts/wacli-monitor-check.sh --target <phone-or-jid> --json This is the default path for monitor jobs because it wraps reconciliation and durable baseline state in one command.
• For one-off/manual "did they reply?" checks where monitor state is not needed, use: skills/wacli/scripts/wacli-recent-reply.sh --target <phone-or-jid> --json
• When authoring a cron monitor, pin the exact wacli-monitor-check.sh command into the job payload. Do not leave the waking run to rediscover the monitor procedure from scratch.
• Do NOT use wacli chats list --query <phone> as the primary discovery path for reply checks or monitors. It can miss the real sibling @lid thread even when replies landed there.
• Do NOT use raw wacli sync + wacli messages list as the primary monitor implementation when wacli-recent-reply.sh covers the same check. Raw sync/list is debug or fallback material, not the default authored monitor path.
• For consumer checks, start with the cheapest read-only probes: skills/wacli/scripts/wacli-health.sh --json --ensure-owner.
• Before drafting a WhatsApp message to a specific person or group, pull the latest conversation context for that exact target. Use wacli-recent-reply.sh or the narrowest chat read/search path that proves what the other person last said. WhatsApp is live chat, so do not draft from memory, stale snippets, or a prior read when current thread context can be checked.
• When reporting the context or proposing a draft, include the exact full text of the latest relevant inbound WhatsApp message(s) from the other person, plus a concise context summary only if it helps. Do not replace the other person's wording with only an AI summary when the actual message text is available.
• Immediately before sending any WhatsApp-as-me message, refresh the same target again and compare it with the context used for the draft. If newer relevant thread movement, inbound or outbound, changes or duplicates the reply, stop and update the reply or ask the user before sending. This is mandatory even if the user already approved an older draft.
• Treat raw wacli doctor as fallback/debug-only. Under a live OpenClaw-owned lock it can report CONNECTED false even when wacli sync --follow is healthy, so do not use it as the primary readiness source for agents.
• When live connectivity matters, prefer skills/wacli/scripts/wacli-live.sh ensure --json to make sure one long-lived wacli sync --follow owner exists for the store.
• Prefer direct safe-bin invocation first. Run one command per call.
• In Normal permissions mode, direct wacli ... commands are allowed. What stays restricted by default is shell wrapping, pipes, chaining, and redirection.
• If you wrap wacli through openclaw nodes run, insert -- before the child argv so flags like --json or --limit reach wacli instead of the wrapper.
• Ban dumb shell chaining, pipes, and redirection around wacli.
• Do NOT use bare wacli sync --json as a health or status probe. wacli sync defaults to --follow=true, so it is a long-running command and a bad fit for quick readiness checks.
• Allow node execution only when the runtime actually supports it; do not claim node exec is invalid just because system.run.prepare is absent.
• If setup is missing or unhealthy, do not dump raw CLI noise back to the user. Treat it as a setup-needed state and use the shared consumer-setup skill.
• Treat send/sync actions as higher-risk than read/list actions. Prove read access first before sending to third parties.
• For send actions, use skills/wacli/scripts/wacli-send-safe.sh as the default path whenever the main ~/.wacli store might already have a live sync owner. This is especially important for monitor-driven replies, Telegram-approved follow-up sends, and any wake flow that decides to answer on WhatsApp after first reading from the shared store. The helper serializes sends per store, pauses/restores the recorded sync owner when needed, and reconciles failed raw-send exits against exact local history.
• Do NOT kill the live sync owner manually, do NOT restart it by hand, and do NOT improvise raw wacli send ... if skills/wacli/scripts/wacli-send-safe.sh covers the same send. Manual stop/send/restart loops are a fallback-of-last-resort debug path, not the authored agent workflow.

Setup Routing

• If wacli is missing, not authenticated, or has no usable chat history yet, route setup through consumer-setup.
• If raw wacli doctor shows AUTHENTICATED true but CONNECTED false, first check skills/wacli/scripts/wacli-health.sh --json --ensure-owner before you tell the user anything. Under lock, the wrapper is the source of truth and raw doctor can be wrong.
• If the user is debugging the live OpenClaw WhatsApp bot/channel, wacli is the wrong surface. The built-in WhatsApp channel is separate from the external wacli CLI.
• Use the raw CLI steps below only when you are the one performing setup or the user explicitly asks for the terminal path.
• For local pairing work, prefer skills/wacli/scripts/wacli-auth-local.sh start. It runs wacli auth in an isolated temp store, captures the terminal QR, renders a real PNG, and returns a session id plus qrPath.
• When returning that QR to the user, send the image itself, not the raw block characters. In CLI-agent flows, include MEDIA:<qrPath> in the final reply so the QR remains scannable.
• After the user scans, confirm completion with skills/wacli/scripts/wacli-auth-local.sh wait --session <id> before claiming WhatsApp is ready.

Safety

• Require explicit recipient + message text.
• Confirm recipient + message before sending.
• Confirmation does not replace the final thread refresh. Re-check the target conversation immediately before wacli-send-safe.sh so approval cannot send a stale or duplicate reply over newer relevant thread movement.
• If anything is ambiguous, ask a clarifying question.

Auth + sync

• wacli auth (QR login + initial sync)
• wacli sync --follow (continuous sync)
• Bounded refresh only when you truly need a live catch-up: wacli sync --once --idle-exit 5s --json
• Raw debug only: wacli doctor

Find chats + messages

• For broad WhatsApp triage, shortlist before deep reads. Start with cheap chat/message discovery such as wacli chats list --limit 20 --json, targeted wacli messages search ... --limit 20, or the existing recent-reply helpers when the target is known.

• Use previews, sender/contact, timestamp, unread/recent state, and helper fields such as recentConversation, latestInboundReply, and continuity to decide what deserves deeper reading.

• Filter obvious noise early: muted group chatter, routine reactions, receipts, automated notifications, and media-only items that do not affect the user's next action.

• Bucket triage results as Urgent, Needs reply soon, Waiting on them, Schedule, Delegate, Archive / no action, or FYI.

• State scope and confidence in every broad triage result: target set, timeframe/search terms, result count or limit, and what was excluded.

• Treat "needs reply" as an inference until recent conversation context shows the user is likely the next responder.

• Before drafting, sending, or monitor-driven reply decisions, use the narrowest current read/check path for the exact target and inspect enough conversation context to avoid answering a stale preview.

• wacli chats list --limit 20 --query "name or number"

• wacli messages search "query" --limit 20 --chat <jid>

• wacli messages search "invoice" --after 2025-01-01 --before 2025-12-31

• Recent-reply reconciliation for monitors/reply checks: skills/wacli/scripts/wacli-recent-reply.sh --target <phone-or-jid> --json This inspects the local wacli.db, resolves real sibling chats from stored names/contacts/aliases, and returns the newest inbound from_me=0 across all candidate chats, plus recentConversation and continuity fields for the active chat.

• Monitor job helper (stateful baseline + reconciliation in one command): skills/wacli/scripts/wacli-monitor-check.sh --target <phone-or-jid> --json This stores baseline state under ~/.openclaw/wacli-monitor-state/ by default so cron jobs can use the same command on every wake. For negotiation/follow-up monitors, do not compose a reply from only latestInboundReply.effectiveText; use recentConversation so the wake run sees prior outbound turns, and suppress sends when continuity.lastOutboundIsRepeatOfPrevious is true unless the user explicitly wants to resend the same line.

History backfill

• wacli history backfill --chat <jid> --requests 2 --count 50

Send

• Text: skills/wacli/scripts/wacli-send-safe.sh text --to "[phone]" --message "Hello! Are you free at 3pm?"
• Group: skills/wacli/scripts/wacli-send-safe.sh text --to "[e-mail]" --message "Running 5 min late."
• File: skills/wacli/scripts/wacli-send-safe.sh file --to "[phone]" --file /path/agenda.pdf --caption "Agenda"
• A successful safe-send means WhatsApp accepted the outbound attempt or the exact outbound row was later found in local history after a failed raw-send exit. Only call it locally verified when the helper reports verification.status as verified_local or verified_local_after_failed_exit; otherwise open the chat or use a manual wa.me fallback before claiming delivery or thread proof.
• Raw wacli send ... is not allowed for real external contacts after safe-send failure. Use it only for self-chat/test contacts or with explicit break-glass approval.
• Raw send fallback for self-chat/test only: wacli send text --to "[phone]" --message "Hello! Are you free at 3pm?"

Monitor-driven reply send pattern

• When a scoped WhatsApp monitor decides that a reply should actually be sent, keep the detection and send paths separate:
  • detection: skills/wacli/scripts/wacli-recent-reply.sh ... --json
  • send: skills/wacli/scripts/wacli-send-safe.sh text --to <phone-or-jid> --message "<approved reply>"
• Do not turn the wake run into a store-lock debugging exercise. The correct authored behavior is: inspect helper output, decide, then call the safe send helper once with pinned args.
• After a manual send, if continued handling would clearly help, offer a scoped monitor for that same WhatsApp thread. Do not start monitoring or promise to drive the whole conversation unless the user explicitly approves the target, cadence, stop condition, expiry, and whether the monitor may only draft or may auto-send.

Notes

• Store dir: ~/.wacli (override with --store).
• Use --json for machine-readable output when parsing.
• Backfill requires your phone online; results are best-effort.
• WhatsApp CLI is not needed for routine user chats; it’s for messaging other people.
• JIDs: direct chats look like <number>@s.whatsapp.net; groups look like <id>@g.us (use wacli chats list to find).
• Do not fabricate <digits>@lid. Linked-ID chats can use opaque @lid values that do not share the phone digits. If you need to check whether a DM got a reply, resolve candidate chats from actual stored data first, then inspect all of them.
• Media replies count as replies. A valid inbound row may have media_type=image (or another media type) with a caption/body, or a media row with empty text where display_text is the only visible clue.
• skills/wacli/scripts/wacli-health.sh --json --ensure-owner is the primary health probe for agents:
  • not_authenticated usually means QR pairing has not been completed yet.
  • paired_not_connected_readable means the account is paired and history is readable, but no live owner is confirmed yet.
  • healthy means OpenClaw has a live owner and chat history is readable.
• Raw wacli doctor is fallback/debug-only:
  • AUTHENTICATED false usually means QR pairing has not been completed yet.
  • AUTHENTICATED true + CONNECTED false may mean the phone/session is offline, or just that another healthy sync owner already holds the store lock.
• wacli chats list --json is the cheapest proof that history/search access is actually working before you attempt send or backfill actions.
• skills/wacli/scripts/wacli-live.sh ensure --json is the preferred minimal live-connection recovery path for agents when WhatsApp is paired but not staying connected.
• skills/wacli/scripts/wacli-health.sh --json --ensure-owner is the preferred normalized readiness check for agents. It intentionally avoids bare wacli sync.