wacli

steipete/clawdis

Send WhatsApp messages to third parties and search chat history via CLI, separate from active conversations.

What is wacli?

wacli is a command-line tool for sending WhatsApp messages to other contacts and syncing/searching your WhatsApp history. Use it when you need to message someone else on WhatsApp or access historical conversations—not for your own active chats, which are handled automatically.

Send text messages to individual contacts or groups via WhatsApp
Search and retrieve WhatsApp message history with date/keyword filtering
List and query your WhatsApp chats by name or number
Backfill chat history by requesting older messages from WhatsApp servers
Send files with captions to contacts or groups
Authenticate and continuously sync WhatsApp data locally

How to install wacli

npx skills add https://github.com/steipete/clawdis --skill wacli

Prerequisites

wacli binary installed (via brew or go)
WhatsApp account with phone number
Phone available for QR code authentication during initial setup

Claude Code

Cursor

Windsurf

Cline

How to use wacli

1.Run `wacli auth` and scan the QR code with your phone to log in and perform initial sync
2.Run `wacli sync --follow` to keep your local WhatsApp data continuously updated
3.Use `wacli chats list --query "name"` to find the recipient's JID (chat identifier)
4.Confirm the recipient and message content before sending
5.Execute `wacli send text --to "<jid>" --message "Your message"` to send the message
6.For files, use `wacli send file --to "<jid>" --file /path/to/file --caption "Caption"`
7.Search history with `wacli messages search "keyword" --chat <jid>` or add date filters

Use cases

Good for

Agent needs to notify a third party about a meeting or status update
Retrieve past messages or invoices from a specific chat for context
Search across all chats for a specific keyword or date range
Send a document or file to a contact as part of a workflow
Backfill missing message history from a chat for analysis

Who it's for

Agents that need to send outbound WhatsApp notifications
Workflows requiring WhatsApp message search or history access
Automation that contacts third parties via WhatsApp

wacli FAQ

When should I use wacli vs. normal WhatsApp chats?

Use wacli only when explicitly asked to message someone else or search history. If you're already chatting with the user on WhatsApp, OpenClaw handles that automatically—do not use wacli for those conversations.

What is a JID and how do I find it?

A JID is the WhatsApp chat identifier. Direct chats look like `<number>@s.whatsapp.net` and groups look like `<id>@g.us`. Use `wacli chats list` to find the JID for a specific contact or group.

Do I need to confirm before sending a message?

Yes. Always require explicit recipient and message text, then confirm both with the user before sending to avoid mistakes.

Can I search messages across all chats?

Yes. Use `wacli messages search "query"` without specifying a chat to search globally, or add `--chat <jid>` to search a specific conversation.

What happens if the backfill fails?

Backfill is best-effort and requires your phone to be online. If it fails, try again later or check `wacli doctor` for connection issues.

Full instructions (SKILL.md)

Source of truth, from steipete/clawdis.

name: wacli description: "Send third-party WhatsApp messages or sync/search WhatsApp history via wacli, not normal active chats." homepage: https://wacli.sh metadata: { "openclaw": { "emoji": "📱", "requires": { "bins": ["wacli"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "steipete/tap/wacli", "bins": ["wacli"], "label": "Install wacli (brew)", }, { "id": "go", "kind": "go", "module": "github.com/steipete/wacli/cmd/wacli@latest", "bins": ["wacli"], "label": "Install wacli (go)", }, ], }, }

wacli

Use wacli only when the user explicitly asks you to message someone else on WhatsApp or when they ask to sync/search WhatsApp history. 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.

Safety

Require explicit recipient + message text.
Confirm recipient + message before sending.
If anything is ambiguous, ask a clarifying question.

Auth + sync

wacli auth (QR login + initial sync)
wacli sync --follow (continuous sync)
wacli doctor

Find chats + messages

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

History backfill

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

Send

Text: wacli send text --to "+14155551212" --message "Hello! Are you free at 3pm?"
Group: wacli send text --to "1234567890-123456789@g.us" --message "Running 5 min late."
File: wacli send file --to "+14155551212" --file /path/agenda.pdf --caption "Agenda"

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).