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/download/whatsapp-cli-darwin-arm64.tar.gz
tar -xzf whatsapp-cli-darwin-arm64.tar.gz
sudo mv whatsapp-cli-darwin-arm64 /usr/local/bin/whatsapp-cli

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

# Windows (x86_64) - download and extract whatsapp-cli-windows-amd64.zip from releases page

Method 3: Build from Source

# Clone repository
git clone https://github.com/vicentereig/whatsapp-cli.git
cd whatsapp-cli

# Install dependencies
go mod download

# Build
go build -o whatsapp-cli .

# Install (optional)
sudo mv whatsapp-cli /usr/local/bin/

# Verify installation
whatsapp-cli --help

Method 4: Install via Go

go install github.com/vicentereig/whatsapp-cli@latest

Release & Distribution Notes

• Version tags use semantic versioning (vMAJOR.MINOR.PATCH). Use a specific tag (e.g., v1.0.0) with go install github.com/vicentereig/whatsapp-cli@v1.0.0 for reproducible builds.
• Pre-built artifacts for Linux/macOS/Windows are published on the GitHub Releases page. Each archive is paired with SHA-256 entries inside checksums.txt; run shasum -a 256 -c checksums.txt --ignore-missing to verify before installing.
• Binaries are named whatsapp-cli-<os>-<arch> (Windows adds .exe). After extraction, mark them executable (chmod +x) and place them somewhere in your PATH such as /usr/local/bin/whatsapp-cli.
• Each uploaded file (including checksums.txt) also has Sigstore cosign signatures (.sig) and certificates (.pem). To verify, run cosign verify-blob --certificate <file>.pem --signature <file>.sig <file>; GitHub Actions uses OIDC identities, so you can enforce provenance on verification.
• To build from source, follow Method 3. That path is ideal when you want to audit the code, tweak compilation flags, or test changes before tagging a release.
• Maintainers can follow docs/RELEASE.md for the step-by-step process that drives go install, source builds, and GitHub Release automation.

Quick Start

Step 1: First-Time Authentication

whatsapp-cli auth

What happens:

1. QR code appears in terminal
2. Open WhatsApp on your phone → Settings → Linked Devices → Link a Device
3. Scan the QR code
4. Session saved to ./store/whatsapp.db

Output:

{
  "success": true,
  "data": {
    "authenticated": true,
    "message": "Successfully authenticated"
  },
  "error": null
}

Session Duration: ~20 days before re-authentication required

Step 2: Sync Messages

Before you can list or search messages, you need to sync them from WhatsApp:

# Start syncing messages (run this in the background or a separate terminal)
whatsapp-cli sync
# Press Ctrl+C when done syncing

What happens:

1. Connects to WhatsApp and stays connected
2. Downloads message history from WhatsApp servers
3. Receives new messages in real-time
4. Stores everything in ./store/messages.db
5. Runs until you press Ctrl+C

Tip: Run sync in a tmux/screen session or as a background service to continuously receive messages.

Step 3: Basic Operations

# List your chats
whatsapp-cli chats list --limit 10

# Search for a contact
whatsapp-cli contacts search --query "John"

# Send a message
whatsapp-cli send --to 1234567890 --message "Hello from CLI!"

# Search messages
whatsapp-cli messages search --query "meeting"

Step 4: Check the Installed Version

whatsapp-cli version

Example Output:

{
  "success": true,
  "data": {
    "version": "v1.1.0"
  },
  "error": null
}

Complete Command Reference

Global Options

All commands support these global flags:

| Flag | Type | Default | Description | |------|------|---------|-------------| | --store | string | ./store | Directory for session and message databases |

Example:

whatsapp-cli --store /var/lib/whatsapp chats list

Command: auth

Authenticate with WhatsApp via QR code.

Syntax:

whatsapp-cli auth

Parameters: None

Returns:

{
  "success": true,
  "data": {
    "authenticated": boolean,
    "message": string
  },
  "error": null
}

Behavior:

• If already authenticated: Returns success immediately
• If not authenticated: Displays QR code and waits for scan
• Timeout: 5 minutes
• Creates store/whatsapp.db with session data

Example:

whatsapp-cli auth
# Scan QR code with phone
# ✓ Successfully authenticated!

Command: sync

⚠️ IMPORTANT: This command must be run to populate the message database. Without running sync, messages list and messages search will return empty results.

Continuously sync messages from WhatsApp to local database. This command:

• Downloads message history from WhatsApp servers
• Receives new incoming messages in real-time
• Stores all messages in SQLite database
• Runs until you press Ctrl+C

Syntax:

whatsapp-cli sync

Parameters: None

Returns: (on exit via Ctrl+C)

{
  "success": true,
  "data": {
    "synced": true,
    "messages_count": 1234
  },
  "error": null
}

Behavior:

• Connects to WhatsApp (authenticates if needed)
• Registers event handlers for incoming messages and history sync
• Processes *events.Message for real-time messages
• Processes *events.HistorySync for message history batches
• Stores all messages in store/messages.db
• Updates progress to stderr (doesn't interfere with JSON output)
• Runs indefinitely until interrupted (Ctrl+C)
• Gracefully disconnects on exit

Progress Output (stderr):

🚀 Starting WhatsApp sync...
✓ Connected to WhatsApp
🔄 Listening for messages... (Press Ctrl+C to stop)
📜 Processing history sync (42 conversations)...
💬 Synced 1234 messages...
^C
✓ Sync completed. Total messages synced: 1234

Examples:

# Basic sync - run in foreground
whatsapp-cli sync

# Run in background (recommended for continuous syncing)
whatsapp-cli sync > sync.json 2> sync.log &

# Run in tmux/screen session
tmux new -s whatsapp
whatsapp-cli sync
# Detach with Ctrl+B D

# Run with custom storage directory
whatsapp-cli --store /var/lib/whatsapp sync

# Stop sync gracefully
kill -INT <pid>
# Or press Ctrl+C in foreground

Use Cases:

1. Initial Setup: Run once to download all message history
2. Continuous Sync: Run as background service to receive messages
3. Periodic Sync: Run via cron to update messages periodically
4. Development: Run in terminal while testing queries

Notes:

• Message history sync may take time depending on message count
• Duplicate messages are handled by SQLite PRIMARY KEY constraints
• Media files are NOT downloaded, only metadata (type, filename, URL)
• Connection stays alive indefinitely until in