wacli-skill/SKILL.md

name, description

name	description
wacli	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

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

Pair/login

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

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

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

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

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

wacli version
wacli auth status
wacli doctor