wacli: WhatsApp from the terminal, with a local SQLite index

What wacli solves, and who it is actually for

WhatsApp has no supported command line interface. The desktop and web clients are graphical, and the official APIs target business messaging rather than a personal account. wacli fills that gap by acting as a linked device: you scan a QR code from the Linked devices screen, and from then on the CLI receives the same message stream a browser tab would. The README describes it as a scriptable WhatsApp client for people and tools that work from the command line.

The audience is narrower than that sentence suggests. It suits someone who already lives in a terminal and wants message history in a form they can query, script, or feed into another process. It also suits integrations that must not accidentally write to WhatsApp, which is why a read-only mode exists. It does not suit anyone who wants a graphical chat client, and it is explicitly not affiliated with WhatsApp or Meta.

Two SQLite databases, one session, and a best-effort history

The architecture has a detail worth understanding before you commit. wacli keeps the WhatsApp session and its own searchable message index in separate SQLite databases. That separation is why search works offline: the query hits the local index, not the network. You can run a search with no live WhatsApp connection at all.

Sync is the second half. wacli sync --follow runs continuously and keeps the local store current, while wacli history requests older per-chat messages from the primary phone. Here the README is blunt: WhatsApp Web provides history on a best-effort basis, and it points to history coverage as the way to inspect what is available locally before asking for more. Treat that as the central constraint of the tool. A linked device does not receive the full archive the way a phone backup would, so anyone expecting a complete export will be disappointed.

Concurrency is handled with a per-store lock. Write commands take it, and when sync --follow owns the lock, supported send commands are delegated to the running sync process rather than competing for it. Two processes writing the same store is therefore a designed-for situation, not an error case.

Installing wacli and running a first search

Homebrew is the shortest path on macOS or Linux. The README gives this single command, and it pulls from the project's own tap:

brew install openclaw/tap/wacli

Prebuilt archives for macOS, Linux and Windows are also published on GitHub Releases, and the README points to docs/install.md for release archives, Docker and platform-specific build requirements. Building from source is where the constraints show up. The repository description states Go 1.26.5 or newer, the README's build section says Go 1.27.0 or newer, and go.mod declares go 1.27.0 with toolchain go1.27.1. The README command is:

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

That CGO_ENABLED=1 is not optional. wacli uses go-sqlite3, so cgo and a C compiler are required, and the repository even ships a test that asserts a CGO_ENABLED=0 build fails with the message wacli_requires_cgo_enabled_1_for_go_sqlite3. The sqlite_fts5 tag is what brings in full-text search.

Once installed, pairing is interactive. Run wacli auth, scan the terminal QR code from WhatsApp's Linked devices screen, and the command performs the first sync after pairing. Then a search reads the local index:

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

Sending requires a recipient you are allowed to contact, and recipients can be phone numbers, WhatsApp JIDs, or synced contact, group and chat names. A useful filter is --has-media, as in wacli messages search "invoice" --has-media. For scripts, --json gives one-shot structured output and --events gives NDJSON lifecycle events from long-running commands, with progress and errors kept on stderr.

The cgo requirement is the real installation cost

Most Go CLIs install as a static binary and run anywhere. wacli does not. Because go-sqlite3 is used, every build path needs cgo and a C compiler, and the project carries that cost into its own tooling: the Dockerfile installs build-base in the build stage, and the build script sets CGO_CFLAGS to suppress a missing-braces warning that would otherwise be treated as an error. If your environment has no C toolchain and you cannot use Homebrew or a release archive, you are not the target user.

The Dockerfile is a reasonable escape hatch. It builds on golang:1.27.1-alpine with build-base, then runs on alpine:3.24 with ca-certificates, ffmpeg and tzdata, creating a wacli user and volumes under /data. It sets WACLI_STORE_DIR=/data/store along with XDG_STATE_HOME, XDG_CONFIG_HOME and XDG_CACHE_HOME, and the entrypoint is wacli with --help as the default command. The ffmpeg dependency is there for media handling, not for messaging itself.

Storage configuration is worth setting deliberately. The default store is ~/.local/state/wacli on Linux and ~/.wacli elsewhere, overridable with --store DIR or WACLI_STORE_DIR. When one machine needs more than one WhatsApp identity, named accounts keep each session, database and lock separate:

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

Read-only mode and where wacli is the wrong tool

The read-only flag is the feature that makes wacli safe to embed. Passing --read-only, or setting WACLI_READONLY=1, means an integration cannot change WhatsApp or the local store. The README shows both forms, including WACLI_READONLY=1 wacli --json doctor. If you are writing a dashboard or a log shipper, that is the mode you want, and the README's companion integrations document covers webhooks and safe read-only SQLite access.

Three cases argue against wacli. First, full history export: the best-effort history model means the local store is a partial mirror, and no amount of syncing changes what the protocol delivers to a linked device. Second, anything requiring official support or a stable contract: wacli uses the WhatsApp Web protocol through whatsmeow and is not affiliated with WhatsApp or Meta, so protocol changes are outside the project's control. Third, a team that cannot build Go with cgo and has no access to the Homebrew tap or release archives will spend its time on toolchain setup rather than on messaging.

The documentation is also uneven in places. The README links to docs/ for accounts, sync, history and integrations, but does not document rollback of a store, and it does not describe what happens to the local index when a linked device is unpaired from the phone. Verify those behaviours yourself before depending on them.

How wacli differs from whatsapp-cli and from the official API

The README credits whatsapp-cli by Vicente Reig as the heavy inspiration, so the closest alternative is the project wacli grew out of. The difference that matters is the local index. wacli mirrors messages into its own SQLite store with full-text search enabled through the sqlite_fts5 build tag, and keeps that store separate from the WhatsApp session database, so search and listing work without a live connection. A thin wrapper around the protocol does not give you that; it gives you commands that hit the network each time.

The other comparison is the official WhatsApp Business API. That route is supported and documented by Meta, but it is aimed at business messaging rather than at reading your own personal chat history, and it does not give you a local SQLite mirror to query. If your goal is to send notifications to customers, wacli is the wrong shape of tool. If your goal is to search your own messages from a shell, the official API does not address the problem at all.

Within the CLI category, the practical distinction is the account model. Named accounts with separate sessions, databases and locks let one installation serve several WhatsApp identities, which is a different design from a single-profile tool that assumes one logged-in user.

Maintenance, licence and what upgrading involves

The repository is not archived, and the last push was on 2026-08-14, which is recent enough that the project is being worked on. The release cadence supports that: v0.16.0 on 2026-08-05, v0.17.0 on 2026-08-13 and v0.17.1 on 2026-08-14. The README lists @steipete as the creator and @dinakars777 as the current maintainer, and there is a CHANGELOG.md at the repository root, so release notes are the place to check before upgrading.

Upgrade cost depends on how you installed it. Homebrew and release archives are straightforward replacements. A source build ties you to the toolchain: Go 1.27.0 or newer per the README, cgo enabled, a C compiler present, and the sqlite_fts5 tag. The Makefile's lint target additionally asserts that the Go version is exactly go1.27.1, which tells you the project pins its own build environment tightly. The repository also carries .goreleaser.yaml and .goreleaser-linux-windows.yaml, so releases are produced by GoReleaser, and there is a make snapshot target for credential-free local release artifacts if you want to reproduce one.

Licensing is MIT, which permits commercial and private use with the usual requirement to preserve the copyright notice and licence text. That is a statement about the licence file, not legal advice. Note that the licence covers wacli itself; the WhatsApp Web protocol it speaks through whatsmeow is a separate matter, and the README's non-affiliation note is the relevant disclosure.

Editorial conclusion

Adopt wacli if you want WhatsApp history in a queryable local store and you are comfortable with a Go toolchain that needs cgo and a C compiler, or with the Homebrew tap. Skip it if you need guaranteed full history export, since the README states WhatsApp Web provides history on a best-effort basis, or if you cannot accept that it is an unofficial client of the WhatsApp Web protocol. Verify first with wacli doctor and wacli history coverage on your own account before you build anything on top of the store.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes