Wacli: Full WhatsApp Control From Your AI Agent

With over 22,000 downloads and 54 stars, the wacli skill by @steipete is the most popular WhatsApp integration on ClawHub. Built by Peter Steinberger on top of the whatsmeow library, it gives Claude complete, offline-first WhatsApp control: send messages and files, search message history, manage contacts and groups, and backfill conversation history — all through the wacli CLI.

The Problem It Solves

WhatsApp has no official API for personal accounts. Meta's Business API exists, but it requires verified business accounts, approved message templates, per-message costs, and weeks of onboarding. For developers and power users who want to automate WhatsApp interactions from their existing account — send a file to a client, search conversation history, notify a team — the options have historically been either brittle browser automation or unsupported third-party hacks.

wacli takes a different approach: it implements the WhatsApp Web protocol directly, synchronizes your full message history locally, and exposes a clean CLI interface that Claude can call. The data stays on your machine. No intermediary servers, no API fees.

Architecture

The skill wraps the wacli binary, which communicates with WhatsApp via the Web protocol (the same channel used by WhatsApp Web in your browser). On first use, you authenticate by scanning a QR code with your phone. After that, wacli maintains an encrypted local store at ~/.wacli that mirrors your message history.

This local-first design means search is instant (no round-trips to WhatsApp servers), and most read operations work even when your phone is offline.

Commands Reference

Auth & Sync

# Initial setup: scan QR code, sync history
wacli auth
 
# Keep history continuously up to date
wacli sync --follow
 
# Check connection health
wacli doctor

wacli auth runs once. After that, wacli sync --follow keeps your local store current in the background.

Finding Contacts and Chats

WhatsApp identifies participants by JID (Jabber ID). Before you can message someone, you need their JID:

# List recent chats, search by name or number
wacli chats list --limit 20 --query "Alice"
 
# JID format: direct chat = +1234567890@s.whatsapp.net
#              group chat  = 1234567890-123456789@g.us

Searching Message History

The full-text search runs against your local SQLite store — no network required:

# Basic keyword search
wacli messages search "invoice" --limit 20
 
# Search within a specific chat
wacli messages search "project update" --chat "+14155551212@s.whatsapp.net"
 
# Date-bounded search
wacli messages search "contract" --after 2025-01-01 --before 2025-12-31

For scripting and parsing, add --json to get machine-readable output:

wacli messages search "delivery" --json | jq '.[].body'

Backfilling History

If you've used WhatsApp on a device that didn't sync older messages:

# Pull 50 older messages from WhatsApp servers, 2 request rounds
wacli history backfill --chat "+14155551212@s.whatsapp.net" --requests 2 --count 50

Note: backfill requires your phone to be online. Results are best-effort — WhatsApp doesn't guarantee full history availability.

Sending Messages and Files

# Send text to a contact
wacli send text --to "+14155551212" --message "Hey, are you free at 3pm?"
 
# Send text to a group
wacli send text --to "1234567890-123456789@g.us" --message "Running 5 min late."
 
# Send a file with caption
wacli send file --to "+14155551212" --file /path/to/agenda.pdf --caption "Agenda for tomorrow"

The skill requires explicit recipient and message text before sending — and always confirms before dispatching, preventing accidental messages.

Safety Model

The skill's skillMd establishes a clear safety protocol:

• Explicit confirmation before every send: Claude shows recipient + message and waits for approval
• Separate from normal chat routing: If you're chatting with Claude via WhatsApp, it won't use wacli to respond — that's routed automatically. wacli is only for messaging third parties
• Ambiguity resolution: Any unclear recipient or intent triggers a clarifying question, not a guess

How It Compares

How to Install

Via Homebrew (recommended for macOS/Linux):

brew install steipete/tap/wacli

Via Go:

go install github.com/steipete/wacli/cmd/wacli@latest

Then install the skill:

clawdbot install wacli

First-time setup:

wacli auth
# Scan the QR code with your WhatsApp mobile app
# Wait for initial history sync to complete

Practical Tips

1. Run wacli sync --follow as a background service. The skill is most useful when your local history is current. On macOS you can add it as a launchd service; on Linux, a systemd user service. This keeps search instant and eliminates the need to backfill before every query.

2. Use --json for any Claude-parsed output. When asking Claude to find a message and extract information, always add --json so the output is structured. Plain text output requires Claude to parse formatting, which adds errors.

3. Get JIDs once and remember them. Ask Claude to run wacli chats list for frequently-messaged contacts and store their JIDs in a note or in your CLAUDE.md. Looking up JIDs repeatedly is wasteful.

4. Date-bound searches cut through noise. WhatsApp threads can have thousands of messages. Use --after and --before to scope searches to relevant time periods — especially useful when searching for project discussions from a specific sprint or event.

5. Backfill strategically. History backfill is slow and requires your phone online. Run it once per chat after initial setup, not before every search.

6. Override the store path for multi-account setups. If you manage multiple WhatsApp accounts, use --store /path/to/account2 to isolate each account's data. Run separate wacli auth sessions for each store path.

Considerations

• WhatsApp protocol compliance: wacli uses the WhatsApp Web protocol, which is not officially sanctioned by Meta for programmatic use. It works reliably, but Meta has been known to rate-limit or ban accounts engaging in unusual automation patterns. Keep usage volumes reasonable.
• Phone dependency at auth: You need your phone to set up the initial connection. After that, most operations are phone-independent.
• No end-to-end encryption verification: Messages are decrypted locally (same as WhatsApp Web), but wacli doesn't provide an independent E2EE verification mechanism.
• Group management complexity: Group JIDs are less intuitive than contact JIDs. Finding the right group ID requires running wacli chats list and scanning output — automation helps here.
• History completeness: WhatsApp's server-side history retention is limited. Very old messages may not be available for backfill, especially if they're from devices that weren't enrolled in WhatsApp's cloud backup.

The Bigger Picture

wacli represents a broader trend: bringing offline-first, local-data tooling to messaging platforms that were designed to be centralized and opaque. By synchronizing history to a local SQLite store, it turns WhatsApp's walled garden into something that can be searched, queried, and integrated — without cloud fees, without API rate limits, and without the months-long approval process that Meta's official Business API requires.

For developers and teams that live in WhatsApp, this is the lowest-friction path to AI-assisted messaging automation that doesn't require switching platforms or negotiating with Meta's business onboarding.

View the skill on ClawHub: wacli