wacli: A CLI for WhatsApp with Local Sync and Search

WhatsApp users looking for command-line control over their messaging now have a new option with wacli, an open-source CLI tool that provides local sync, search, and message management capabilities.

Built on top of the whatsmeow library, wacli focuses on three core features: best-effort local synchronization of message history, fast offline search, and message sending functionality. The tool is designed as a third-party application using the WhatsApp Web protocol and is not affiliated with WhatsApp itself.

Installation and Setup

wacli offers multiple installation options for users:

• Homebrew: brew install steipete/tap/wacli
• Local build: go build -tags sqlite_fts5 -o ./dist/wacli ./cmd/wacli

After installation, the default storage directory is ~/.wacli, though this can be overridden with the --store DIR flag.

Core Functionality

The tool follows a straightforward workflow:

1. Authentication: wacli auth displays a QR code for login and performs initial data sync
2. Continuous sync: wacli sync --follow maintains ongoing synchronization without requiring re-authentication

Key Features

Message Management

• Search: wacli messages search "meeting" provides fast offline search across all messages
• History backfill: Users can request older messages with wacli history backfill --chat [jid] --requests 10 --count 50
• Media download: Messages with media attachments can be downloaded after syncing

Message Sending

• Text messages: wacli send text --to 1234567890 --message "hello"
• File attachments: wacli send file --to 1234567890 --file ./pic.jpg --caption "hi"
• Custom filenames: Override display names with --filename flag

Contact and Group Management

• Group listing: wacli groups list
• Group renaming: wacli groups rename --jid [email protected] --name "New name"

Technical Implementation

The tool uses SQLite with FTS5 (Full-Text Search) capabilities for efficient message storage and retrieval. Environment variables provide additional customization:

• WACLI_DEVICE_LABEL: Sets the linked device label shown in WhatsApp
• WACLI_DEVICE_PLATFORM: Overrides the linked device platform (defaults to CHROME)

Backfilling Message History

Since wacli sync only stores messages sent by WhatsApp Web opportunistically, users can request older messages through the history backfill feature. This process requires the primary WhatsApp device to be online and works on a per-chat basis, using the oldest locally stored message as an anchor point.

A script is provided for bulk backfilling across all chats, making it easier to populate message history for multiple conversations.

Prior Art and Inspiration

wacli acknowledges its inspiration from the whatsapp-cli by Vicente Reig, learning from its implementation while providing its own approach to WhatsApp CLI functionality.

Current Status

The core implementation is complete and functional, with recent updates in version 0.2.0 adding enhanced message search capabilities and improved file sending options.

The project is available under an open-source license, with full design notes available in the documentation.

For developers and power users who prefer command-line interfaces, wacli offers a compelling alternative to graphical WhatsApp clients, particularly for those who need robust search capabilities and automation features.

GitHub Repository