---
name: wacli
description: Build and use the local wacli WhatsApp CLI for QR pairing, syncing, chat/message reads, and sending messages without browser DOM automation.
---

# wacli

Use this when the task is about WhatsApp via the local `wacli` CLI instead of WhatsApp Web DOM automation.

## What it is

`wacli` is built locally from `/root/projects/wacli` and the binary lives at:

- `/root/projects/wacli/dist/wacli`

Local Go 1.25 was installed at:

- `/usr/local/go1.25.0/bin/go`

## Use this, not the browser, when

- you need to pair WhatsApp with a QR code
- you need to list chats
- you need to read recent messages from the local sync store
- you need to search messages offline
- you need to send text, replies, reactions, or files

## Safe defaults

- For read-only inspection, prefer `--json --read-only`.
- For sending or syncing, omit `--read-only`.
- Prefer machine-readable output for agent use.
- The default store is `/root/.local/state/wacli`.
- Prefer `wacli` from PATH now that it is installed globally.
- Prefer the CLI over WhatsApp Web DOM automation whenever the task is supported by `wacli`.

## Command patterns

### Read-only status

```bash
wacli --json --read-only auth status
wacli --json --read-only doctor
```

### Pair/login

```bash
wacli auth
```

Notes:
- `auth` is the command that shows the QR code and bootstraps initial sync.
- `sync` never shows a QR; it only works after auth succeeds.

### Sync

```bash
wacli sync --follow
wacli sync --once
```

Notes:
- `sync --once` really connects, syncs, then exits after an idle window.
- `sync` warns when local storage is uncapped; prefer `--max-messages` or `--max-db-size` for long-running use.

### Chats

```bash
wacli --json --read-only chats list --limit 50
wacli --json --read-only chats show --jid <chat-jid>
```

Real-world note:
- After auth + sync, chat metadata and recent timestamps are available offline from the local DB.

### Messages

```bash
wacli --json --read-only messages list --chat <chat-jid> --limit 20
wacli --json --read-only messages search "<query>"
wacli --json --read-only messages context --chat <chat-jid> --id <message-id> --before 3 --after 3
```

Real-world note:
- `messages context` is good enough to inspect a reply chain around a specific message without opening WhatsApp Web.

### Send

```bash
wacli send text --to <recipient> --message "..."
wacli send file --to <recipient> --file <path> --caption "..."
wacli send react --to <recipient> --id <message-id> --reaction "👍"
```

Recipients can be:
- JID
- phone number
- synced contact/group/chat name

If a name is ambiguous, use a JID or add selection flags supported by `wacli`.

Known local alias:
- `jonna` → Jonna

## Agent notes

- For new environments, verify the binary exists before using it.
- If a build is needed again, use Go 1.25 from `/usr/local/go1.25.0/bin`.
- If module fetches fail because of flaky DNS, retry before assuming the repo is broken.
- Do not claim messages are available until a real auth + sync happened.

## Useful verification

```bash
wacli version
wacli auth status
wacli doctor
```