WhatsApp CLI - Complete Reference

For Humans & LLMs: This document covers the WhatsApp CLI tool: installation, usage, the API reference, examples, architecture, and troubleshooting. Humans and large language models can both read it.

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?

WhatsApp CLI is a standalone command-line tool for WhatsApp. It uses the WhatsApp Web multidevice protocol. Every command returns structured JSON output. Use it 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). For reproducible builds, use a specific tag, for example v1.0.0, with go install github.com/vicentereig/whatsapp-cli@v1.0.0.
• The GitHub Releases page has pre-built artifacts for Linux, macOS, and Windows. Each archive has a matching SHA-256 entry in checksums.txt. Before you install, run shasum -a 256 -c checksums.txt --ignore-missing to verify the archive.
• Binaries use the name whatsapp-cli-<os>-<arch> (Windows adds .exe). After you extract the file, mark it executable with chmod +x and place it in your PATH, for example /usr/local/bin/whatsapp-cli.
• Each uploaded file, including checksums.txt, also has a Sigstore cosign signature (.sig) and certificate (.pem). To verify a file, run cosign verify-blob --certificate <file>.pem --signature <file>.sig <file>. GitHub Actions uses OIDC identities, so you can enforce provenance during verification.
• To build from source, follow Method 3. Use this method to audit the code, change compilation flags, or test changes before you tag a release.
• Maintainers can follow the steps in docs/RELEASE.md. It covers 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 list or search messages, 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 or screen session, or as a background service, so it keeps receiving 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: Run this command to fill the message database. If you do not run sync, messages list and messages search return empty results.

Sync messages from WhatsApp to the local database continuously. This command:

• Downloads message history from WhatsApp servers
• Receives new messages in real time
• Stores all messages in the 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
• Sends progress to stderr (does not affect JSON output)
• Runs until interrupted (Ctrl+C)
• 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 on a schedule
4. Development: Run in terminal while testing queries

Notes:

• Message history sync can take time. The duration depends on the number of messages.
• SQLite PRIMARY KEY constraints prevent duplicate messages.
• The CLI does not download media files. It stores only metadata: type, filename, and URL.
• The connection stays open until you interrupt it.
• You can restart the sync safely. It does not create duplicate messages.

---

Command: messages list

List messages from all chats or a specific chat.

Syntax:

whatsapp-cli messages list [OPTIONS]

Parameters:

Flag	Type	Required	Default	Description
--chat	string	No	-	Filter by chat JID (e.g., 1234567890@s.whatsapp.net)
--limit	int	No	20	Maximum number of messages to return
--page	int	No	0	Page number for pagination (0-indexed)

Returns:

{
  "success": true,
  "data": [
    {
      "id": "msg_unique_id",
      "chat_jid": "1234567890@s.whatsapp.net",
      "chat_name": "John Doe",
      "sender": "1234567890",
      "content": "Message text content",
      "timestamp": "2025-10-26T10:30:00Z",
      "is_from_me": false,
      "media_type": ""
    }
  ],
  "error": null
}

Examples:

# List 50 most recent messages across all chats
whatsapp-cli messages list --limit 50

# List messages from specific chat
whatsapp-cli messages list --chat 1234567890@s.whatsapp.net

# Pagination: Get second page of results
whatsapp-cli messages list --limit 20 --page 1

# Get JID first, then list messages
JID=$(whatsapp-cli contacts search --query "Alice" | jq -r '.data[0].jid')
whatsapp-cli messages list --chat "$JID" --limit 100

Sorting: Messages returned in reverse chronological order (newest first)

---

Command: messages search

Search messages by content across all chats.

Syntax:

whatsapp-cli messages search --query TEXT [OPTIONS]

Parameters:

Flag	Type	Required	Default	Description
--query	string	Yes	-	Search term (case-insensitive, partial match)
--limit	int	No	20	Maximum number of results
--page	int	No	0	Page number for pagination

Returns: Same format as messages list

Examples:

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

# Search with more results
whatsapp-cli messages search --query "project" --limit 100

# Case-insensitive search
whatsapp-cli messages search --query "URGENT"  # Finds "urgent", "Urgent", etc.

Search Behavior:

• Case-insensitive
• Partial word matching
• Searches message content only (not sender names)
• Returns messages from all chats

---

Command: contacts search

Search contacts by name or phone number.

Syntax:

whatsapp-cli contacts search --query TEXT

Parameters:

Flag	Type	Required	Default	Description
--query	string	Yes	-	Search term for name or phone number

Returns:

{
  "success": true,
  "data": [
    {
      "phone_number": "1234567890",
      "name": "John Doe",
      "jid": "1234567890@s.whatsapp.net"
    }
  ],
  "error": null
}

Examples:

# Search by name
whatsapp-cli contacts search --query "John"

# Search by partial phone number
whatsapp-cli contacts search --query "5551234"

# Extract JID for further operations
JID=$(whatsapp-cli contacts search --query "Alice" | jq -r '.data[0].jid')
echo "Alice's JID: $JID"

Behavior:

• Returns maximum 50 results
• Excludes group chats (only individual contacts)
• Sorted alphabetically by name
• Partial matching on both name and JID

---

Command: chats list

List all chats sorted by recent activity.

Syntax:

whatsapp-cli chats list [OPTIONS]

Parameters:

Flag	Type	Required	Default	Description
--query	string	No	-	Filter chats by name or JID
--limit	int	No	20	Maximum number of chats
--page	int	No	0	Page number for pagination

Returns:

{
  "success": true,
  "data": [
    {
      "jid": "1234567890@s.whatsapp.net",
      "name": "John Doe",
      "last_message_time": "2025-10-26T10:30:00Z"
    }
  ],
  "error": null
}

Examples:

# List 20 most recent chats
whatsapp-cli chats list

# List all chats (with pagination)
whatsapp-cli chats list --limit 100

# Filter chats by name
whatsapp-cli chats list --query "Team"

# Get list of all group chats
whatsapp-cli chats list | jq '.data[] | select(.jid | endswith("@g.us"))'

Sorting: Chats ordered by last_message_time (most recent first)

Chat Types:

• Individual chats: JID ends with @s.whatsapp.net
• Group chats: JID ends with @g.us

---

Command: send

Send a text message to an individual or group.

Syntax:

whatsapp-cli send --to RECIPIENT --message TEXT

Parameters:

Flag	Type	Required	Default	Description
--to	string	Yes	-	Phone number or JID
--message	string	Yes	-	Message text content

Recipient Formats:

Format	Example	Use Case
Phone number	1234567890	Individual chats (auto-converted to JID)
Individual JID	1234567890@s.whatsapp.net	Individual chats
Group JID	123456789@g.us	Group chats (must use JID)

Returns:

{
  "success": true,
  "data": {
    "sent": true,
    "recipient": "1234567890",
    "message": "Hello!"
  },
  "error": null
}

Examples:

# Send to individual (phone number)
whatsapp-cli send --to 1234567890 --message "Hello from CLI!"

# Send to individual (full JID)
whatsapp-cli send --to 1234567890@s.whatsapp.net --message "Hi there!"

# Send to group (requires JID)
whatsapp-cli send --to 123456789@g.us --message "Hello everyone!"

# Send with special characters (use quotes)
whatsapp-cli send --to 1234567890 --message "It's working! 🎉"

# Multi-line messages
whatsapp-cli send --to 1234567890 --message "Line 1
Line 2
Line 3"

# Send result of command
whatsapp-cli send --to 1234567890 --message "Server status: $(uptime)"

Behavior:

• Requires active connection (authenticates if needed)
• Message stored locally in database
• Returns immediately after sending (does not wait for delivery)
• Supports Unicode (emojis, international characters)

Limitations:

• The send command supports text messages only. To download attachments, use media download.
• No delivery/read receipt information returned
• Maximum message length: WhatsApp's standard limit (~65,536 characters)

---

Command: media download

Download media attachments (images, videos, audio, documents) that sync stored in the local database.

Syntax:

whatsapp-cli media download --message-id ID [--chat JID] [--output PATH]

Parameters:

Flag	Type	Required	Description
--message-id	string	Yes	Message identifier from messages list/search
--chat	string	No	Chat JID to disambiguate duplicate message IDs
--output	string	No	Destination file or directory (defaults to auto-structured path)

Default storage:

• The CLI stores media next to the SQLite databases, under STORE/media/{chat}/{message}/{media_type}/filename
• The CLI sanitizes paths automatically
• If --output points to a directory, the CLI uses the original filename (or a name based on the message ID)

Return value:

{
  "success": true,
  "data": {
    "message_id": "ABCD1234",
    "chat_jid": "1234567890@s.whatsapp.net",
    "path": "/path/to/media/1234567890@s.whatsapp.net/ABCD1234/image/ABCD1234.jpg",
    "bytes": 204800,
    "media_type": "image",
    "mime_type": "image/jpeg",
    "downloaded_at": "2025-02-01T12:34:56.789Z"
  },
  "error": null
}

Examples:

# Download image using auto-organised directory layout
whatsapp-cli media download --message-id ABCD1234

# Save into a specific directory (filename auto-generated)
whatsapp-cli media download --message-id ABCD1234 --output /tmp/media/

# Save using explicit path and disambiguate by chat JID
whatsapp-cli media download --message-id XYZ987 --chat 1234567890@s.whatsapp.net --output ~/Downloads/report.pdf

Notes:

• Requires that whatsapp-cli sync captured the message metadata first
• The sync loop downloads media in the background, without blocking new messages
• If you run the command again, it overwrites the existing file with a fresh download
• Errors include metadata issues (an expired link or a missing direct path) or file permission problems

---

JSON Response Format

All commands return JSON in this format:

Success Response

{
  "success": true,
  "data": <result_data>,
  "error": null
}

Error Response

{
  "success": false,
  "data": null,
  "error": "Error message describing what went wrong"
}

Data Types by Command

Command	Data Type	Structure
auth	object	{"authenticated": bool, "message": string}
messages list	array	[Message, ...]
messages search	array	[Message, ...]
contacts search	array	[Contact, ...]
chats list	array	[Chat, ...]
send	object	{"sent": bool, "recipient": string, "message": string}

---

Usage Examples

Example 1: Send Daily Report via Cron

#!/bin/bash
# File: /usr/local/bin/daily-report.sh

RECIPIENT="1234567890"  # Your phone number

# Generate report
REPORT=$(cat <<EOF
📊 Daily Report - $(date +%Y-%m-%d)

Server Status: $(systemctl is-active nginx)
Disk Usage: $(df -h / | awk 'NR==2 {print $5}')
Memory: $(free -h | awk 'NR==2 {print $3 "/" $2}')
Uptime: $(uptime -p)
EOF
)

# Send via WhatsApp
whatsapp-cli send --to "$RECIPIENT" --message "$REPORT"

Cron entry:

0 9 * * * /usr/local/bin/daily-report.sh

Example 2: Search and Bulk Message

#!/bin/bash
# Send message to all contacts matching "Team"

CONTACTS=$(whatsapp-cli contacts search --query "Team" | jq -r '.data[].jid')

for JID in $CONTACTS; do
  whatsapp-cli send --to "$JID" --message "Team meeting at 3 PM today!"
  sleep 2  # Rate limiting
done

Example 3: Export Chat History

#!/bin/bash
# Export specific chat to JSON file

JID="1234567890@s.whatsapp.net"
OUTPUT_FILE="chat_export_$(date +%Y%m%d).json"

# Get all messages (paginated)
PAGE=0
ALL_MESSAGES=[]

while true; do
  RESPONSE=$(whatsapp-cli messages list --chat "$JID" --limit 100 --page $PAGE)
  MESSAGES=$(echo "$RESPONSE" | jq '.data')
  COUNT=$(echo "$MESSAGES" | jq 'length')

  if [ "$COUNT" -eq 0 ]; then
    break
  fi

  ALL_MESSAGES=$(echo "$ALL_MESSAGES" | jq ". + $MESSAGES")
  PAGE=$((PAGE + 1))
done

echo "$ALL_MESSAGES" | jq '.' > "$OUTPUT_FILE"
echo "Exported to $OUTPUT_FILE"

Example 4: Monitor for Keywords

#!/bin/bash
# Alert when specific keywords appear in messages

ALERT_RECIPIENT="your_phone@s.whatsapp.net"
LAST_CHECK_FILE="/tmp/whatsapp_last_check"

# Get timestamp of last check
if [ -f "$LAST_CHECK_FILE" ]; then
  LAST_CHECK=$(cat "$LAST_CHECK_FILE")
else
  LAST_CHECK=$(date -u -d "1 hour ago" +%Y-%m-%dT%H:%M:%SZ)
fi

# Search for urgent messages since last check
MESSAGES=$(whatsapp-cli messages search --query "URGENT" --limit 100 | \
  jq --arg since "$LAST_CHECK" '.data[] | select(.timestamp > $since)')

if [ -n "$MESSAGES" ]; then
  COUNT=$(echo "$MESSAGES" | jq -s 'length')
  whatsapp-cli send --to "$ALERT_RECIPIENT" \
    --message "⚠️ $COUNT urgent messages found!"
fi

# Update last check timestamp
date -u +%Y-%m-%dT%H:%M:%SZ > "$LAST_CHECK_FILE"

---

Integration with LLMs/AI Tools

Parsing JSON with jq

# Extract specific fields
whatsapp-cli contacts search --query "John" | jq '.data[0].jid'
# Output: "1234567890@s.whatsapp.net"

# Count results
whatsapp-cli chats list | jq '.data | length'
# Output: 42

# Filter and transform
whatsapp-cli messages list | jq '[.data[] | {name: .chat_name, msg: .content}]'

Python Integration

#!/usr/bin/env python3
import subprocess
import json

def whatsapp_cli(command):
    """Execute whatsapp-cli command and return parsed JSON."""
    result = subprocess.run(
        ['whatsapp-cli'] + command.split(),
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

# Search contacts
contacts = whatsapp_cli('contacts search --query "Team"')
if contacts['success']:
    for contact in contacts['data']:
        print(f"{contact['name']}: {contact['jid']}")

# Send message
result = whatsapp_cli('send --to 1234567890 --message "Hello from Python!"')
print(f"Message sent: {result['success']}")

Node.js/TypeScript Integration

import { execSync } from 'child_process';

interface WhatsAppResponse<T> {
  success: boolean;
  data: T | null;
  error: string | null;
}

function whatsappCli<T>(command: string): WhatsAppResponse<T> {
  const output = execSync(`whatsapp-cli ${command}`).toString();
  return JSON.parse(output);
}

// Usage
const contacts = whatsappCli<Contact[]>('contacts search --query "Alice"');
if (contacts.success && contacts.data) {
  const jid = contacts.data[0].jid;
  whatsappCli(`send --to ${jid} --message "Hi from Node!"`);
}

Claude Code / Codex Integration

// Example Claude Code MCP tool wrapper

import { execSync } from 'child_process';

export const whatsappTools = {
  sendMessage: async (to: string, message: string) => {
    const result = execSync(
      `whatsapp-cli send --to "${to}" --message "${message}"`
    ).toString();
    return JSON.parse(result);
  },

  searchContacts: async (query: string) => {
    const result = execSync(
      `whatsapp-cli contacts search --query "${query}"`
    ).toString();
    return JSON.parse(result);
  },

  getRecentMessages: async (chatJid: string, limit = 20) => {
    const result = execSync(
      `whatsapp-cli messages list --chat "${chatJid}" --limit ${limit}`
    ).toString();
    return JSON.parse(result);
  }
};

// Use in Claude Code
const contacts = await whatsapp