WhatsApp CLI
A Go utility with JSON output: an agent reads WhatsApp chats, searches messages and contacts and sends texts from your number
- 206 ★ on the repository
- Last commit
Broad access
Why this level
- Gives an agent read access to all chats and the ability to send messages in your name, including groups
- `store/whatsapp.db` holds account login data, and the unofficial protocol can get a number banned
Install
- Works in
Manual install
brew install vicentereig/tap/whatsapp-cliRecommended way. Alternatives: prebuilt binaries from releases, `go install github.com/vicentereig/whatsapp-cli@latest`, a source build (Go 1.24 or newer).
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Gives an agent read access to all chats and the ability to send messages in your name, including groups
- `store/whatsapp.db` holds account login data, and the unofficial protocol can get a number banned
This is third-party code. Review the repository files before installing.
What it does
WhatsApp CLI is a single Go binary for a personal WhatsApp account. It connects to the WhatsApp Web multi-device protocol through the whatsmeow library, and every command returns JSON. That lets Claude Code, Codex and plain scripts read chats, search messages and contacts, download media and send text to private and group chats. Sign-in happens once by QR code with `whatsapp-cli auth`, and the session then lasts about 20 days. `whatsapp-cli sync` stores messages in a local SQLite database, so `whatsapp-cli messages search` does not go to the network. Session keys live in `store/whatsapp.db` and chat history in `store/messages.db`.
Who it is for. Developers and operators who want to give an agent or a script access to their own WhatsApp: reminders, cron reports, chat exports.
Good fit when
- A scheduled script sends a morning report to you or a team in WhatsApp
- An agent has to find an agreement in your chats by keyword and show the relevant messages
- A chat history has to be exported to JSON and processed with jq or Python
- A bot watches incoming messages and reacts to key phrases while you are busy
Not a fit when
- You need the official WhatsApp Business API for customer broadcasts: the utility acts as a linked device of a personal account
- The account cannot risk a ban: the utility uses the unofficial WhatsApp Web protocol
- The machine is shared and `store/whatsapp.db` cannot be protected: that file grants access to the account
- Messages have to go out from several numbers at once: the utility handles one account
Example request
Search my WhatsApp for messages containing "contract" from the last week and show who wrote them and whenLimitations
- The utility is unofficial and built on the WhatsApp Web protocol. The author rates the ban risk as low but gives no guarantee.
- `store/whatsapp.db` holds the account login data, so protect it like a password and keep it out of git.
- The session lasts about 20 days, then a new QR sign-in is needed. WhatsApp allows up to five linked devices.
- After WhatsApp updates the library may answer `Client outdated (405)` and close the connection, which means updating the whatsmeow dependency.
How to disable. In the WhatsApp app open Linked devices and remove the utility's device. Then delete the `store/` folder (session and history), and remove the binary with Homebrew or by hand.
FAQ
How do I install WhatsApp CLI?
The simplest way is Homebrew: `brew install vicentereig/tap/whatsapp-cli`. There are prebuilt binaries for Linux, macOS and Windows on the releases page, a source build and `go install github.com/vicentereig/whatsapp-cli@latest`.
How do I sign in?
Run `whatsapp-cli auth`: a QR code appears in the terminal and you scan it in the WhatsApp app under linked devices. Then `whatsapp-cli sync` loads messages into the local database.
How do I send a message?
With `whatsapp-cli send --to 1234567890 --message "Hello"`. The `--to` value can be a number, a personal chat JID or a group JID ending in `@g.us`.
Where do my messages go?
According to the author, data stays on your machine: chats are stored in local SQLite, there is no cloud sync, and traffic uses the encrypted WhatsApp Web protocol.
Can I cut the agent off from the account?
Yes. Remove the device in WhatsApp's linked devices on the phone and the session becomes invalid. The files in `store/` can then be deleted.
Discussion
No questions or reviews yet.
Related
CLI toolsAn MCP server for your personal WhatsApp account: search and read chats, contacts, send messages and files through an agent
An MCP server for personal WhatsApp: read and search chats, send text and files, react, send voice notes and transcribe them
An MCP server searches and reads owned WhatsApp history as a linked device so agents can find messages and prepare summaries.
Telegram MCP by chaindead
Telegram MCP
A Go MCP server for your Telegram account: the agent reads dialogs and unread messages, marks them read, leaves replies as drafts
WeCom CLI
wecom-cli
The official WeCom CLI with 15 agent skills: messages, docs, calendar, meetings, mail and disk from the terminal
Claude-to-IM
claude-to-im
A bridge between Claude Code or Codex and messengers: talk to the agent from Telegram, Discord, Feishu, QQ or WeChat
README in short
The README is meant as a complete reference for humans and language models. It starts with an overview and four install methods, then a quick start, every command with flags and examples, the JSON response format, example scenarios with cron and chat exports, and snippets for Python and Node.js. It closes with the data model, storage, a security section, the architecture and troubleshooting.