wacli-skill/EXAMPLES.md

wacli CLI examples

This is a practical example pack for the current wacli CLI surface.

Placeholders used below:

• <chat-jid> → something like 491627201491@s.whatsapp.net or 120363172152129541@g.us
• <group-jid> → a group JID ending in @g.us
• <contact-jid> → a contact JID ending in @s.whatsapp.net
• <message-id> → a WhatsApp message ID from messages list / messages search
• <sender-jid> → the original sender JID, needed for some group reply/react flows
• <invite-code> → the code portion from a WhatsApp group invite link

Global flags

Use these on almost any command:

wacli --json ...
wacli --read-only ...
wacli --store /custom/path/to/wacli-store ...
wacli --timeout 30s ...
wacli --lock-wait 20s ...
wacli --full ...

Examples:

wacli --json --read-only auth status
wacli --store ~/.local/state/wacli --json chats list --limit 100
wacli --timeout 10m doctor --connect

Auth

Pair with QR and bootstrap sync

wacli auth
wacli auth --follow
wacli auth --download-media
wacli auth --idle-exit 45s
wacli auth --qr-format text

Pair by phone number instead of QR

wacli auth --phone +491234567890

Check auth status

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

Logout

wacli auth logout

Sync

One-shot sync

wacli sync --once
wacli sync --once --idle-exit 60s
wacli sync --once --refresh-contacts --refresh-groups

Long-running sync

wacli sync --follow
wacli sync --follow --download-media
wacli sync --follow --max-reconnect 10m

Guardrails / caps

wacli sync --once --max-messages 50000
wacli sync --once --max-db-size 2GB
wacli sync --follow --max-db-size 500MB --download-media

Chats

List chats

wacli chats list
wacli chats list --limit 100
wacli chats list --query jonna
wacli --json --read-only chats list --limit 1000

Show one chat

wacli chats show --jid <chat-jid>
wacli --json --read-only chats show --jid <chat-jid>

Contacts

Search contacts

wacli contacts search jonna
wacli contacts search paul --limit 10
wacli --json --read-only contacts search chef

Show one contact

wacli contacts show --jid <contact-jid>
wacli --json --read-only contacts show --jid <contact-jid>

Refresh contacts from the whatsmeow store

wacli contacts refresh

Aliases

wacli contacts alias set --jid <contact-jid> --alias jonna
wacli contacts alias rm --jid <contact-jid> --alias jonna

Tags

wacli contacts tags add --jid <contact-jid> --tag family
wacli contacts tags add --jid <contact-jid> --tag school
wacli contacts tags rm --jid <contact-jid> --tag school

Messages

List messages

wacli messages list
wacli messages list --limit 20
wacli messages list --chat <chat-jid> --limit 50
wacli messages list --chat <chat-jid> --from-me --limit 20
wacli messages list --chat <chat-jid> --from-them --limit 20
wacli messages list --sender <sender-jid> --limit 50
wacli messages list --forwarded --limit 50
wacli messages list --after 2026-05-01 --before 2026-05-06 --limit 100
wacli messages list --chat <chat-jid> --asc --limit 100
wacli --json --read-only messages list --chat <chat-jid> --limit 200

Search messages

wacli messages search "meeting"
wacli messages search "jonna" --limit 20
wacli messages search "photo" --has-media
wacli messages search "invoice" --type document
wacli messages search "voice" --type audio
wacli messages search "vacation" --chat <chat-jid>
wacli messages search "forwarded" --forwarded
wacli messages search "project" --from <sender-jid>
wacli messages search "trip" --after 2026-05-01 --before 2026-05-31
wacli --json --read-only messages search "meeting" --chat <chat-jid> --limit 100

Show a single message

wacli messages show --chat <chat-jid> --id <message-id>
wacli --json --read-only messages show --chat <chat-jid> --id <message-id>

Show context around a message

wacli messages context --chat <chat-jid> --id <message-id>
wacli messages context --chat <chat-jid> --id <message-id> --before 10 --after 10
wacli --json --read-only messages context --chat <chat-jid> --id <message-id> --before 3 --after 3

Send

Send text

wacli send text --to +491234567890 --message "hello"
wacli send text --to jonna --message "yo"
wacli send text --to <chat-jid> --message "this is a test"
wacli send text --to "Jonna😜" --pick 1 --message "hi"

Reply to a message

wacli send text --to <chat-jid> --reply-to <message-id> --message "replying here"
wacli send text --to <group-jid> --reply-to <message-id> --reply-to-sender <sender-jid> --message "got it"

Send files

wacli send file --to jonna --file ./pic.jpg
wacli send file --to jonna --file ./pic.jpg --caption "look at this"
wacli send file --to <chat-jid> --file ./clip.mp4 --caption "video test"
wacli send file --to <chat-jid> --file ./voice.ogg --mime audio/ogg
wacli send file --to <chat-jid> --file ./report.pdf --filename report-may.pdf
wacli send file --to <group-jid> --file ./notes.txt --reply-to <message-id>
wacli send file --to <group-jid> --file ./photo.png --reply-to <message-id> --reply-to-sender <sender-jid>

React to messages

wacli send react --to <chat-jid> --id <message-id> --reaction "👍"
wacli send react --to <chat-jid> --id <message-id> --reaction "🔥"
wacli send react --to <group-jid> --id <message-id> --sender <sender-jid> --reaction "😂"

Remove a reaction

wacli send react --to <chat-jid> --id <message-id> --reaction ""

Media

Download media for a message

wacli media download --chat <chat-jid> --id <message-id>
wacli media download --chat <chat-jid> --id <message-id> --output ./downloads/
wacli media download --chat <chat-jid> --id <message-id> --output ./downloads/photo.jpg
wacli --json media download --chat <chat-jid> --id <message-id>

Groups

List groups

wacli groups list
wacli groups list --limit 100
wacli groups list --query school
wacli --json --read-only groups list --limit 500

Refresh / inspect groups live

wacli groups refresh
wacli groups info --jid <group-jid>
wacli --json groups info --jid <group-jid>

Join / leave / rename groups

wacli groups join --code <invite-code>
wacli groups leave --jid <group-jid>
wacli groups rename --jid <group-jid> --name "New Group Name"

Manage participants

wacli groups participants add --jid <group-jid> --user +491111111111
wacli groups participants add --jid <group-jid> --user +491111111111 --user +492222222222
wacli groups participants remove --jid <group-jid> --user +491111111111
wacli groups participants promote --jid <group-jid> --user +491111111111
wacli groups participants demote --jid <group-jid> --user +491111111111

Invite links

wacli groups invite link get --jid <group-jid>
wacli groups invite link revoke --jid <group-jid>

History backfill

Pull older messages from the primary device

wacli history backfill --chat <chat-jid>
wacli history backfill --chat <chat-jid> --requests 3 --count 50
wacli history backfill --chat <chat-jid> --requests 10 --count 100 --wait 90s
wacli history backfill --chat <chat-jid> --idle-exit 10s
wacli --json history backfill --chat <chat-jid> --requests 2 --count 50

Presence

Typing indicators

wacli presence typing --to <chat-jid>
wacli presence typing --to <chat-jid> --media audio
wacli presence paused --to <chat-jid>

Profile

Set profile picture

wacli profile set-picture ./avatar.jpg
wacli profile set-picture ./avatar.png

Doctor / diagnostics

wacli doctor
wacli --json doctor
wacli doctor --connect

Completion scripts

Bash

wacli completion bash
source <(wacli completion bash)
wacli completion bash > /etc/bash_completion.d/wacli
wacli completion bash --no-descriptions

Zsh

wacli completion zsh
source <(wacli completion zsh)
wacli completion zsh > "${fpath[1]}/_wacli"
wacli completion zsh --no-descriptions

Fish

wacli completion fish
wacli completion fish | source
wacli completion fish > ~/.config/fish/completions/wacli.fish
wacli completion fish --no-descriptions

PowerShell

wacli completion powershell
wacli completion powershell | Out-String | Invoke-Expression
wacli completion powershell --no-descriptions

Version

wacli version
wacli --json version

Handy read-only inspection patterns

wacli --json --read-only auth status
wacli --json --read-only chats list --limit 200
wacli --json --read-only messages list --chat <chat-jid> --limit 50
wacli --json --read-only messages search "meeting" --limit 100
wacli --json --read-only messages context --chat <chat-jid> --id <message-id> --before 5 --after 5
wacli --json --read-only contacts show --jid <contact-jid>

Notes

• auth is the command that shows the QR and bootstraps sync.
• sync never shows a QR; it only works after auth succeeds.
• For scripted reads, prefer --json --read-only.
• For ambiguous contact/group names, use --pick N where supported or pass the JID directly.
• Some group reply/react flows need the original sender JID in addition to the message ID.