wu

WhatsApp CLI tool — like gh is to GitHub, wu is to WhatsApp.

Built on @whiskeysockets/baileys.

Install

npm install -g @ibrahimwithi/wu-cli

Requires Node.js 20+.

Quick Start

# Authenticate (scan QR code)
wu login

# Or use pairing code instead
wu login --code 15551234567

# Start collecting messages
wu listen

# Search messages
wu messages search "meeting tomorrow"

# Send a message
wu messages send [email protected] "Hello!"

# List your groups
wu groups list --live

By default, wu operates in opt-in mode — no messages are collected until you allow specific chats:

# Allow all group messages (read-only)
wu config allow '*@g.us' --mode read

# Allow full access to a specific chat
wu config allow [email protected]

# Start collecting
wu listen

Commands

Authentication

Messages

# Send with media
wu messages send [email protected] --media photo.jpg --caption "Check this out"

# Create a poll
wu messages send [email protected] --poll "Lunch?" --options "Pizza,Sushi,Tacos"

# Reply to a message
wu messages send [email protected] "Agreed" --reply-to BAE5ABC123

# Search within a specific chat
wu messages search "budget" --chat [email protected] --limit 20

# Download all undownloaded media in a chat
wu media download-batch [email protected] --limit 50 --concurrency 4

# Export all messages since a timestamp to a file
wu messages export [email protected] --after 1772548621 --format jsonl --output data/export.jsonl

# Export as readable markdown
wu messages export [email protected] --format markdown --output data/chat.md

Chats & Contacts

Groups

By default wu groups list shows every group you're in (jid + name + community shape) so you can see what's there before opting in. Description, full participant list, and messages stay constraint-gated. Set whatsapp.group_discovery: false in the config to revert to the old behavior where group metadata is only stored when the constraint allows.

Communities

Direct messages (DMs)

DM JIDs contain the contact's phone number, so they're always constraint-gated regardless of group_discovery.

Media

History

# Backfill 50 older messages for a group
wu history backfill [email protected] --count 50

# With JSON output
wu history backfill [email protected] --count 20 --json

Daemon

# Run as a foreground daemon — collects messages continuously
wu daemon

# Install as a systemd service (Linux)
wu daemon install

# Remove systemd service
wu daemon uninstall

# View daemon logs
wu daemon logs

The daemon auto-reconnects on connection drops, logs health every 5 minutes, and stores all messages to SQLite.

Remote Sync

Run the daemon on a VPS collecting messages 24/7, query from your local machine. All communication over SSH — no exposed ports, no extra auth.

# --- On the VPS ---
npm i -g @ibrahimwithi/wu-cli
wu login
wu daemon install

# --- On your local machine ---
# Add the remote
wu remote add vps user@your-vps-ip

# Push your constraints to the server
wu remote setup vps --push

# Pull the database
wu sync pull

# Continuous sync every 30s
wu sync pull --watch --interval 30

# Install as a systemd timer (Linux)
wu sync install --interval 60

When a remote is configured and no local daemon is running, wu mcp starts in remote mode — reads from the local synced DB, routes writes (send, react, etc.) through SSH to the VPS.

MCP Server

# Start MCP server (stdio transport for AI agents)
wu mcp

Exposes WhatsApp as tools and resources for AI agents via the Model Context Protocol. See MCP setup guide for Claude Code, Cursor, Codex CLI, and Gemini CLI configuration.

The MCP server operates in three modes:

Configuration

Database

Constraints

The constraint system controls what wu can do with each chat. Three modes:

Resolution order (most specific wins):

1. Exact JID match ([email protected])
2. Wildcard domain (*@g.us for all groups, *@s.whatsapp.net for all DMs)
3. Default constraint
4. Implicit fallback: none

# Set default to read-only for everything
wu config default read

# Full access for one group
wu config allow [email protected]

# Block a specific chat
wu config block [email protected]

# Read-only for all groups
wu config allow '*@g.us' --mode read

Configuration

Config lives at ~/.wu/config.yaml:

whatsapp:
  read_receipts: false     # Send read receipts (default: false)
  media_max_mb: 50         # Max media auto-download size in MB
  send_delay_ms: 1000      # Delay before sending messages (ms)
  group_discovery: true    # Cache group metadata even when constraint is 'none'
                           # (jid + name + community shape only; descriptions
                           # and participants stay constraint-gated). Set to
                           # false for strict mode.

constraints:
  default: none            # Default constraint mode
  chats:
    "*@g.us":
      mode: read
    "[email protected]":
      mode: full

remotes:
  vps:
    host: user@your-vps-ip
    wu_home: ~/.wu
default_remote: vps

db:
  path: ~/.wu/wu.db        # SQLite database path

log:
  level: info              # debug, info, warn, error

All runtime data lives under ~/.wu/ (override with WU_HOME env var).

JSON Output

Most commands support --json for machine-readable output. When piped, wu listen auto-detects and switches to JSON:

# Pipe messages to jq
wu listen | jq '.body'

# Export messages as JSON
wu messages list [email protected] --json --limit 1000

MCP Tools and Resources

When running wu mcp, the following are available to AI agents:

Tools: wu_messages_send, wu_react, wu_media_download, wu_media_download_batch, wu_messages_search, wu_messages_list, wu_messages_context, wu_messages_count, wu_messages_export, wu_history_backfill, wu_chats_list, wu_chats_search, wu_dms_list, wu_contacts_list, wu_contacts_search, wu_groups_list, wu_groups_info, wu_groups_invite, wu_groups_create, wu_groups_leave, wu_groups_rename, wu_groups_join, wu_communities_list, wu_constraints_list, wu_constraints_set, wu_constraints_remove, wu_constraints_default, wu_config_show, wu_status

Resources: wu://chats, wu://chats/{jid}/messages, wu://contacts, wu://contacts/{jid}, wu://groups, wu://groups/{jid}, wu://status

Exit Codes

License

MIT