wacli

wacli 🗃️ — WhatsApp from your terminal

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.

Install

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.

Quick start

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.

Keep messages in sync

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.

Use wacli from scripts

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.

Commands

Area	What it covers
auth, accounts	Pair a linked device and manage isolated account stores.
sync, history	Mirror new events and request older per-chat history.
messages, calls	Search, inspect, export, and manage local records.
send, media	Send text and files or download synced media.
contacts, chats	Find people and manage local or remote chat state.
groups, channels	Inspect and manage groups, communities, and channels.
profile, presence	Manage profile details and chat presence.
store, doctor	Inspect local storage and diagnose the setup.

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

Configuration

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

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

Credits

Heavily inspired by whatsapp-cli by Vicente Reig.

Maintainers

• Created by @steipete
• Currently maintained by @dinakars777

License

MIT.