gem-hunter

wacli is a scriptable WhatsApp client for people and tools that work from the command line. It pairs as a linked device, mirrors messages into a local SQLite store, and supports search, sending, and chat management.

wacli uses the WhatsApp Web protocol through whatsmeow. It is not affiliated with WhatsApp or Meta.

Homebrew on macOS or Linux:

brew install openclaw/tap/wacli

Prebuilt archives for macOS, Linux, and Windows are available from GitHub Releases. Official macOS binaries require macOS 15 (Sequoia) or newer.

To build from source, install Go 1.27.0 or newer and a C compiler, then run:

CGO_ENABLED=1 CGO_CFLAGS="-Wno-error=missing-braces" \
  go install -tags sqlite_fts5 github.com/openclaw/wacli/cmd/wacli@latest

See the installation guide for release archives, Docker, and platform-specific build requirements.

Pair the CLI by scanning the terminal QR code from WhatsApp's Linked devices screen. auth performs the first sync after pairing.

wacli auth
wacli messages search "meeting"
wacli send text --to +15551234567 --message "hello"

Sending requires a recipient you are allowed to contact. Recipients can be phone numbers, WhatsApp JIDs, or synced contact, group, and chat names.

The quickstart covers phone-number pairing, named accounts, media, and diagnostics.

Run a continuous sync to keep the local store current:

wacli sync --follow

wacli keeps the WhatsApp session and its own searchable message index in separate SQLite databases. Search reads the local index, so it works without a live WhatsApp connection:

wacli messages search "invoice" --has-media
wacli --json messages list --limit 20

WhatsApp Web provides history on a best-effort basis. Use history coverage to inspect what is available locally before requesting older messages from the primary phone.

Human-readable tables are the default. Use --json for one-shot commands and --events for NDJSON lifecycle events from long-running commands. Progress and errors stay on stderr.

Use --read-only or WACLI_READONLY=1 when an integration must not change WhatsApp or the local store:

wacli --read-only --json messages search "invoice"
WACLI_READONLY=1 wacli --json doctor

Write commands take a per-store lock. After a sync --follow process finishes startup, supported send commands, the chats state commands (mark-read, archive, pin, mute, and their inverses), contacts check, and contacts save are delegated to it while it owns that lock. See companion integrations for webhooks and safe read-only SQLite access.

The complete documentation is at wacli.sh, or run wacli help <command> for the installed command reference.

The default store is ~/.local/state/wacli on Linux and ~/.wacli elsewhere. Override it with --store DIR or WACLI_STORE_DIR; use named accounts when each WhatsApp identity needs its own session, database, and lock.

wacli accounts add work
wacli --account work sync --follow

See accounts for store selection and sync for storage limits, media downloads, webhooks, and presence behavior.

Development uses the Go 1.27.3 toolchain selected by go.mod, Node.js 24 or newer, pnpm, cgo, and a C compiler. The source minimum remains Go 1.27.0.

pnpm install --frozen-lockfile
pnpm build
pnpm format:check && pnpm lint && pnpm test

Heavily inspired by whatsapp-cli by Vicente Reig.

• Created by @steipete
• Currently maintained by @dinakars777

MIT.