`wacli` is a command-line interface (CLI) tool for WhatsApp, built on top of `whatsmeow`. It provides functionalities for local message history synchronization, fast offline search, sending messages,
wacli is a command-line interface (CLI) tool for WhatsApp, built on top of whatsmeow. It provides functionalities for local message history synchronization, fast offline search, sending messages, and contact/group management.
This guide will walk you through the installation, basic setup, and a quick start to using wacli.
You can install wacli either via Homebrew (for macOS and Linux) or by building it from source.
To install wacli using Homebrew, tap the repository and then install the package:
If you prefer to build wacli from the source code, follow these steps:
Clone the wacli repository.
Navigate to the repository directory.
Build the executable, ensuring sqlite_fts5 tags are included for full-text search capabilities:
This will create an executable named wacli inside the ./dist directory.
After installation or building, you can run wacli commands.
To see the available commands and general help:
Note on pnpm wacli: Throughout the quick start examples, pnpm wacli is often used. This assumes you are in the wacli project root and have pnpm installed and configured as per the package.json scripts. If you installed via Homebrew or built locally and are running the executable directly, replace pnpm wacli with wacli (if wacli is in your PATH) or ./dist/wacli.
wacli stores its data (session, message history, contacts, etc.) by default in ~/.wacli. You can override this location for any command using the --store DIR flag.
Here's a quick guide to get you started with the core functionalities of wacli.
The first step is to authenticate your wacli instance with WhatsApp. This involves scanning a QR code from your primary WhatsApp device (your phone) and then initiates an initial sync of your message history.
The command will display a QR code in your terminal. Scan this QR code using the "Linked Devices" feature in your WhatsApp mobile app.
Once authenticated, you can run wacli in a follow mode to continuously capture new messages and updates. This command does not show a QR code and requires prior authentication.
To check the status of your wacli store, authentication, and search capabilities, use the doctor command:
wacli provides fast offline search of your synced message history.
wacli sync primarily captures new messages. To retrieve older messages for a specific chat, you can request an on-demand history sync from your primary device. This is a best-effort process and requires your primary device to be online.
--chat: The JID (Jabber ID) of the chat you want to backfill (e.g., [email protected] for DMs or [email protected] for groups).--requests: The number of backfill requests to attempt.--count: The number of messages to request per on-demand sync (recommended: 50).You can loop through all known chats in your local DB and attempt to backfill history for each:
This script requires jq to be installed for JSON processing.
After messages containing media (images, videos, documents) have been synced, you can download the media files locally.
--chat: The JID of the chat containing the media message.--id: The unique ID of the message containing the media.wacli allows you to send text messages and files to contacts or groups.
--to: Recipient's phone number or JID.--message: The text content of the message.--to: Recipient's phone number or JID.--file: Path to the file you want to send.--caption: (Optional) A caption for the file (for images, videos, documents).You can list your known groups and perform basic management tasks.
--jid: The JID of the group.--name: The new name for the group.