WhatsCLI

WhatsApp Web CLI — a TypeScript alternative to wacli, powered by Baileys.

What is it

WhatsCLI is a command-line tool to automate WhatsApp Web. Focused on:

• 🔐 Secure auth — QR code login → session persisted locally
• 📥 Offline sync — message history stored in SQLite with FTS5 search
• 🔍 Fast search — full-text search without internet
• 📤 Sending — text, files, reactions, quoted replies
• 🚀 Stealth Bulk Send — automated safe messaging with random delays, typing simulation, and message rotation (spintax)
• 👥 Management — contacts, chats, groups
• 🇧🇷 Smart JID — automatic phone number resolution (fixes the Brazilian 9th digit ghost-chat issue)
• 🤖 OpenClaw-ready — --json output optimized for OpenClaw ingestion

[!NOTE] For AI Agents: Detailed technical context, schema, and CLI guidelines for AI interactions are available in Docs/AI_CONTEXT.md.

Prerequisites

• Node.js >= 20.x
• npm >= 9.x

Requirements

• Node.js: >= 20.17.0 or >= 22.9.0 (LTS versions are highly recommended).
• npm: Compatible with the chosen Node.js version.
• Native Modules: If pre-built binaries for sharp are not available for your environment, ensure you have build tools installed (make, g++, python).

Installation

Via Homebrew (Recommended for macOS/Linux)

brew tap thiagobarbosa-dev/tap
brew install whatscli

Via NPM (Global)

npm install -g @thiagobarbosa-dev/whatscli

From Source

1. Clone the repository:

   git clone https://github.com/thiagobarbosa-dev/whatscli.git
   cd whatscli

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Link for global usage:

   npm link

Quick Start

# 1. Authenticate (shows QR code)
whatscli auth

# 2. Sync messages
whatscli sync --once

# 3. Search messages
whatscli messages search "meeting" --json

# 4. List recent chats
whatscli chats list

### `send text`
Send a plain text message to a JID or phone number.
```bash
whatscli send text "5511999998888" "Hello!"

send-bulk

Send messages in bulk with mandatory anti-ban stealth measures. Supports .json and .csv.

whatscli send-bulk recipients.json --message "Hi {{name}}!" --min-delay 30 --max-delay 90

Recipient Formats

JSON (recipients.json):

[
  { "jid": "5511999998888", "name": "Name" },
  { "jid": "5511977776666", "name": "Name" }
]

CSV (recipients.csv):

jid,name,city
5511999998888,Name,City Name
5511977776666,Name,City Name

• Features:
  • 🔄 Spintax: {Hello|Hi|Hey} {{name}}! will rotate greetings.
  • 🧪 Variables: Any key in JSON or column in CSV can be used as {{key}}.
  • 🕒 Human-like: Simulates "typing..." presence based on message length and WPM.
  • 🛡️ Anti-Ban: Mandatory randomized delays and server-side JID resolution.

Diagnostics

whatscli doctor

---

## Commands

| Group | Command | Description |
|-------|---------|-------------|
| **Auth** | `auth` | QR login, `auth status`, `auth logout` |
| **Sync** | `sync` | Sync messages (`--once` or `--follow`) |
| **Messages** | `messages list\|search\|show\|context` | List and search messages |
| **Send** | `send text\|file\|react` | Send message, file, or reaction |
| **Media** | `media download` | Download media from a message |
| **History** | `history backfill` | Request older history |
| **Contacts** | `contacts search\|show` | Search and view contacts |
| **Chats** | `chats list\|show` | List conversations |
| **Groups** | `groups list\|search\|members\|info\|rename\|leave\|participants` | Manage groups and members |
| **Presence** | `presence typing\|recording\|paused` | Presence indicators |
| **Doctor** | `doctor` | Environment diagnostics |

### Global Flags

--store DIR data directory (default: ~/.whatscli) --json JSON output (for scripts / OpenClaw) --full disable table truncation --timeout DUR timeout for non-sync commands --read-only block all write operations

---

## JSON Output (OpenClaw spec)

When using `--json` or piping, output follows this schema:

```json
{
  "id": "MSG_ID",
  "chat": "[email protected]",
  "chat_name": "Group Name",
  "sender": "[email protected]",
  "sender_name": "Sender Name",
  "from_me": false,
  "timestamp": 1714000000,
  "type": "text",
  "content": "message content here",
  "quoted_id": null,
  "media_path": null
}

Development

# Dev mode
npx ts-node src/index.ts --help

# Build
npm run build

# Lint
npm run lint

Disclaimer

This project is not affiliated with WhatsApp. Use responsibly and in accordance with WhatsApp's Terms of Service.

License

MIT