Wacli – WhatsApp CLI

WhatsApp CLI built on top of whatsmeow, focused on:

• Best-effort local sync of message history + continuous capture
• Fast offline search
• Sending messages
• Contact + group management

This is a third-party tool that uses the WhatsApp Web protocol via whatsmeow and is not affiliated with WhatsApp.

Core implementation is in place. See docs/spec.md for the full design notes.

• Messages: search/list includes display text for reactions, replies, and media types.
• Send: wacli send file --filename to override the display name.
• Auth: optional WACLI_DEVICE_LABEL / WACLI_DEVICE_PLATFORM env overrides.

Choose one of the following options.

If you install via Homebrew, you can skip the local build step.

brew install steipete/tap/wacli

go build -tags sqlite_fts5 -o ./dist/wacli ./cmd/wacli

Run (local build only):

./dist/wacli --help

Default store directory is ~/.wacli (override with --store DIR).

# 1) Authenticate (shows QR), then bootstrap sync
pnpm wacli auth
# 2) Keep syncing (never shows QR; requires prior auth)
pnpm wacli sync --follow
# Diagnostics
pnpm wacli doctor
# Search messages
pnpm wacli messages search "meeting"
# Backfill older messages for a chat
pnpm wacli history backfill --chat [email protected] --requests 10 --count 50
# Download media
./wacli media download --chat [email protected] --id <message-id>
# Send a message
pnpm wacli send text --to 1234567890 --message "hello"
# Send a file
./wacli send file --to 1234567890 --file ./pic.jpg --caption "hi"
# List groups
pnpm wacli groups list

This project is heavily inspired by the excellent whatsapp-cli by Vicente Reig.

wacli auth: interactive login (shows QR code), then immediately performs initial data sync. wacli sync: non-interactive sync loop (never shows QR; errors if not authenticated).

• Output is human-readable by default; pass --json for machine-readable output.

Defaults to ~/.wacli (override with --store DIR).

WACLI_DEVICE_LABEL: set the linked device label (shown in WhatsApp). WACLI_DEVICE_PLATFORM: override the linked device platform (defaults to CHROME if unset or invalid).

wacli sync stores whatever WhatsApp Web sends opportunistically. To try to fetch older messages, use on-demand history sync requests to your primary device (your phone).

Important notes:

• This is best-effort: WhatsApp may not return full history.
• Your primary device must be online.
• Requests are per chat (DM or group).
• Recommended --count is 50 per request.