WhatsApp CLI - Complete Reference

For Humans & LLMs: This document contains comprehensive information about the WhatsApp CLI tool, including installation, usage, API reference, examples, architecture, and troubleshooting. It is designed to be parsed by both humans and large language models.

Version: 1.3.2 Repository: https://github.com/vicentereig/whatsapp-cli License: MIT Language: Go 1.24+

Table of Contents

• Overview
• Installation
• Quick Start
• Complete Command Reference
• JSON Response Format
• Usage Examples
• Integration with LLMs/AI Tools
• Data Model
• Storage & Persistence
• Authentication & Security
• Architecture
• Error Handling
• Troubleshooting
• Development
• FAQ
• Credits

Overview

What is WhatsApp CLI?

A standalone command-line interface for WhatsApp built on the WhatsApp Web multidevice protocol. Every command returns structured JSON output, making it ideal for:

• Automation: Shell scripts, cron jobs, CI/CD pipelines
• AI Integration: Codex, Claude Code, GPT-based tools
• Data Analysis: Extract and analyze WhatsApp conversations
• Custom Applications: Build tools on top of WhatsApp

Key Features

| Feature | Description | |---------|-------------| | Zero Dependencies | Single compiled binary (21MB), no runtime required | | JSON Output | All commands return structured JSON for easy parsing | | Persistent Sessions | Authenticate once via QR code, auto-reconnect for ~20 days | | Local Storage | SQLite database, no cloud dependencies | | Full Messaging | Send, receive, search messages; manage contacts & chats | | Group Support | Send/receive messages in group chats | | TDD Implementation | 100% test coverage, production-ready |

System Requirements

• Operating System: Linux, macOS, Windows
• Architecture: x86_64, ARM64
• Go Version: 1.24+ (for building from source)
• Storage: ~50MB for binary + variable for message database
• Network: Internet connection required
• WhatsApp Account: Active WhatsApp account with smartphone

Installation

Method 1: Homebrew (Recommended)

brew install vicentereig/tap/whatsapp-cli

Or tap first, then install:

brew tap vicentereig/tap
brew install whatsapp-cli

Method 2: Download Pre-built Binary

# Linux (x86_64)
curl -LO https://github.com/vicentereig/whatsapp-cli/releases/latest/download/whatsapp-cli-linux-amd64.tar.gz
tar -xzf whatsapp-cli-linux-amd64.tar.gz
sudo mv whatsapp-cli-linux-amd64 /usr/local/bin/whatsapp-cli

# macOS (ARM64 - M1/M2/M3)
curl -LO https://github.com/vicentereig/whatsapp-cli/releases/latest...