DOCSEARCHbyAlgolia
Submit Docs

wacli Documentation

repository·main·Indexed 25 days ago

https://github.com/openclaw/wacli

A scriptable WhatsApp CLI client built on whatsmeow. wacli allows users to pair as a linked device, sync messages into a local SQLite store for offline search, and manage chats, groups, and messaging via the command line. It supports multiple account management, history backfilling from primary devices, and provides a set of commands for authentication, message searching, and sending text, files, or status updates.

Tokens
36.1K
Snippets
84
Records
268
Agent score
77%

What's inside wacli

  1. Overview of wacli functionality

    main

    wacli is a Go-based CLI that pairs as a linked WhatsApp Web device. It mirrors message history into a local SQLite database with FTS5 full-text search capabilities. It is designed for use in terminals, shell pipelines, and by AI coding agents.

    Key capabilities include:

    • Message Syncing: Mirrors messages and status broadcasts to a local SQLite store.
    • Search: Fast, offline message searching via SQLite FTS5.
    • Chat Management: Control chat states (archive, pin, mute, read/unread) and filter lists by these states.
    • Scripting Support: Provides stable output via human-readable tables, --json for stdout, and NDJSON via --events for long-running commands. Progress and errors are sent to stderr to keep pipes clean.
    • Agent-Friendly Mode: Use --read-only (or WACLI_READONLY=1) to prevent any commands from mutating WhatsApp or local state.
    • Storage Management: Cap local growth using --max-messages or --max-db-size.

  2. Overview of wacli

    main
    wacli is a WhatsApp CLI built on whatsmeow. It allows you to pair as a linked WhatsApp Web device, store message metadata locally for offline search, and execute workflows for sending messages, media, managing groups, and contacts via scripts or manual CLI commands. You can manage multiple WhatsApp identities using named accounts via the --account flag.

  3. Build wacli for local development

    main

    For developers working within the repository, use the provided Makefile to build and verify the project.

    git clone https://github.com/openclaw/wacli.git
cd wacli
make build
make check
./dist/wacli --version

  4. Pair wacli as a linked device

    main

    Use wacli auth to generate a QR code in your terminal. Scan this code using WhatsApp on your phone (Linked devices → Link a device) to authenticate. Once paired, the command will automatically begin the initial sync.

    Alternative pairing methods:

    • If the QR code is hard to scan, use --qr-format text to get a raw payload.
    • Pair via phone number using --phone +15551234567.

  5. Quick start with wacli

    main

    Follow these steps to pair your device, sync messages, and perform basic actions.

    1. Pair your device: Run wacli auth to show a QR code for WhatsApp pairing.
    2. Sync messages: Run wacli sync --follow to keep syncing in the background (requires prior authentication).
    3. Search messages: Use wacli messages search "<query>" to search your local SQLite store.
    4. Send messages/files:
      • Text: wacli send text --to <recipient> --message "<text>"
      • Files: wacli send file --to <recipient> --file <path> --caption "<text>"
      • Status: wacli send status --message "<text>" --background-color '<color>'
    5. Run diagnostics: Use wacli doctor to check system health.
    wacli auth
wacli sync --follow
wacli messages search "meeting"
wacli send text --to 1234567890 --message "hello"
wacli send file --to mom --file ./pic.jpg --caption "hi"
wacli send status --message "available today" --background-color '#1f7a8c'
wacli doctor

  6. Backfill WhatsApp Message History

    main

    Since WhatsApp Web history is best-effort, you can request older messages for a specific chat using the history commands. This sends an on-demand request to your primary device.

    • wacli history backfill --chat JID [--count 50] [--requests N]: Attempts to fetch older messages.
      • Limits: --count must be $\le 500$; --requests must be $\le 100$.
    • wacli history coverage: Inspects local chat/message coverage without connecting.
    • wacli history fill --dry-run: Plans which chats match local anchors without writing or connecting.

    Note: During backfill, automatic initial history-sync blob downloads are disabled; only on-demand history-sync notifications are processed.

  7. Sync WhatsApp messages in the background

    main

    Use the sync command to keep your local message store updated. This requires a previously authenticated session.

    • --follow: Reconnects on errors and keeps syncing continuously.
    • --once: Exits after one idle window.
    • --max-messages / --max-db-size: Limits the local store size (can also be set via WACLI_SYNC_MAX_* environment variables).
    wacli sync --follow

  8. Import contacts from a JSON or NDJSON file

    main

    Instead of using macOS Contacts, you can import contact names from a file using the --input FILE flag. The file can be a JSON array or Newline Delimited JSON (NDJSON).

    Supported JSON Formats:

    JSON Array:

    [
  {
    "full_name": "Alice Appleseed",
    "phones": ["+1 (415) 734-7847"]
  }
]

    NDJSON:

    {"full_name":"Alice Appleseed","phones":["+1 (415) 734-7847"]}
{"first_name":"Bob","last_name":"Builder","phones":["0043 664 104 2436"]}

    Contact Object Schema:

    • full_name (string)
    • first_name (string)
    • last_name (string)
    • phones (array of strings)

    Note: Phone matching strips non-digits. Leading 00 prefixes are normalized to + format.

    Usage:

    wacli contacts import-system --input contacts.json --dry-run
wacli contacts import-system --input contacts.ndjson
    wacli contacts import-system --input contacts.json --dry-run

  9. Authenticate and pair wacli via QR code

    main
    To authenticate a new WhatsApp device, use the wacli auth command. This is an interactive process that displays a QR code in your terminal. Once you scan the code with your WhatsApp mobile app, wacli will automatically begin a bootstrap sync to pull in your message history and metadata. The command will exit once the initial sync becomes idle, unless you provide the --follow flag.
    wacli auth

  11. Manage multiple named accounts

    main

    If you use multiple WhatsApp numbers, you can create isolated stores and sessions using named accounts.

    • Add account: wacli accounts add <name> (use --no-auth to skip immediate pairing).
    • List accounts: wacli accounts list.
    • Use specific account: Prefix any command with --account <name>.
    wacli accounts add work
wacli accounts list
wacli --account work sync --follow
wacli --account personal send text --to mom --message "hi"

  12. Diagnose wacli health with the doctor command

    main

    Use wacli doctor to diagnose issues related to store layout, authentication state, Full-Text Search (FTS) support, database locks, or live connectivity.

    By default, the command reports local health information without establishing a live connection to WhatsApp. To include live connectivity checks, use the --connect flag. Note that --connect requires existing authentication and the store lock to be available.

    Key diagnostic information provided includes:

    • Local store counts
    • Authentication identity (when available)
    • FTS/search state
    • Lock details
    wacli doctor
# For live connectivity checks:
wacli doctor --connect