LinuxCommandLibrary
GitHubF-DroidGoogle Play Store

wacli

WhatsApp CLI for local sync, search, and messaging

TLDR

Authenticate by scanning a QR code from your primary WhatsApp device
$ wacli auth
copy
Search synced message history for a keyword
$ wacli messages search "[keyword]"
copy
Send a text message to a contact
$ wacli send text --to [phone_number] --message "[message]"
copy
Send a file with a caption
$ wacli send file --to [phone_number] --file [path/to/file] --caption "[caption]"
copy
List all chats
$ wacli chats list
copy
Run a continuous sync loop in the background
$ wacli sync --follow
copy
Request older messages from primary device
$ wacli history backfill --chat [chat_jid] --count [50]
copy

SYNOPSIS

wacli \<command\> [options]

DESCRIPTION

wacli is a command-line interface for WhatsApp built on the whatsmeow library. It provides best-effort local synchronization of message history, fast offline full-text search, message sending, and contact and group management, all from the terminal.Authentication is performed by scanning a QR code displayed in the terminal from your primary WhatsApp device. Once authenticated, wacli stores session data, messages, contacts, and media references in a local SQLite database at ~/.wacli by default. The sync command captures incoming messages continuously, while history backfill requests older messages from the primary device on demand.Search uses SQLite FTS5 for fast full-text queries with LIKE fallback, returning results with contextual snippets. All output defaults to human-readable format with --json available for scripting and automation.

PARAMETERS

auth

Interactive login via QR code and initial data sync
sync
Non-interactive sync loop; requires prior authentication
sync --follow
Keep syncing continuously
messages search query
Search synced messages using FTS5 full-text search
messages list [--chat jid] [--limit n]
List messages, optionally filtered by chat
history backfill --chat jid [--count n] [--requests n]
Fetch older messages from primary device
media download --chat jid --id msgid_
Download media for a specific message
send text --to recipient --message text
Send a text message to a contact or group
send file --to recipient --file path [--caption text] [--filename name]
Send a file with optional caption and display name override
chats list
List all chats
groups list
List all groups
groups rename --jid groupjid **--name** newname
Rename a group
doctor
Run diagnostics on the local store
--store DIR
Override default store directory (default: ~/.wacli)
--json
Machine-readable JSON output

CAVEATS

wacli is a third-party tool that uses the WhatsApp Web protocol via whatsmeow and is not affiliated with WhatsApp. WhatsApp actively bans accounts using third-party clients, and bans are often permanent with no appeal process. History backfill is best-effort and requires the primary device to be online. Media downloads depend on WhatsApp's content retention policies.

HISTORY

wacli was created by Peter Steinberger (steipete) and written in Go. The project was first released in 2025 with a focus on providing a native terminal experience for WhatsApp, enabling local message synchronization and offline search capabilities that the official WhatsApp clients do not offer.

SEE ALSO

signal-cli(1), neomutt(1)

Copied to clipboard
Kai