120 lines
3.0 KiB
Markdown
120 lines
3.0 KiB
Markdown
---
|
|
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
|
|
```
|