# wacli CLI examples This is a practical example pack for the current `wacli` CLI surface. Placeholders used below: - `` → something like `491627201491@s.whatsapp.net` or `120363172152129541@g.us` - `` → a group JID ending in `@g.us` - `` → a contact JID ending in `@s.whatsapp.net` - `` → a WhatsApp message ID from `messages list` / `messages search` - `` → the original sender JID, needed for some group reply/react flows - `` → the code portion from a WhatsApp group invite link ## Global flags Use these on almost any command: ```bash wacli --json ... wacli --read-only ... wacli --store /custom/path/to/wacli-store ... wacli --timeout 30s ... wacli --lock-wait 20s ... wacli --full ... ``` Examples: ```bash 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 ```bash 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 ```bash wacli auth --phone +491234567890 ``` ### Check auth status ```bash wacli auth status wacli --json --read-only auth status ``` ### Logout ```bash wacli auth logout ``` ## Sync ### One-shot sync ```bash wacli sync --once wacli sync --once --idle-exit 60s wacli sync --once --refresh-contacts --refresh-groups ``` ### Long-running sync ```bash wacli sync --follow wacli sync --follow --download-media wacli sync --follow --max-reconnect 10m ``` ### Guardrails / caps ```bash 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 ```bash wacli chats list wacli chats list --limit 100 wacli chats list --query jonna wacli --json --read-only chats list --limit 1000 ``` ### Show one chat ```bash wacli chats show --jid wacli --json --read-only chats show --jid ``` ## Contacts ### Search contacts ```bash wacli contacts search jonna wacli contacts search paul --limit 10 wacli --json --read-only contacts search chef ``` ### Show one contact ```bash wacli contacts show --jid wacli --json --read-only contacts show --jid ``` ### Refresh contacts from the whatsmeow store ```bash wacli contacts refresh ``` ### Aliases ```bash wacli contacts alias set --jid --alias jonna wacli contacts alias rm --jid --alias jonna ``` ### Tags ```bash wacli contacts tags add --jid --tag family wacli contacts tags add --jid --tag school wacli contacts tags rm --jid --tag school ``` ## Messages ### List messages ```bash wacli messages list wacli messages list --limit 20 wacli messages list --chat --limit 50 wacli messages list --chat --from-me --limit 20 wacli messages list --chat --from-them --limit 20 wacli messages list --sender --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 --asc --limit 100 wacli --json --read-only messages list --chat --limit 200 ``` ### Search messages ```bash 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 wacli messages search "forwarded" --forwarded wacli messages search "project" --from wacli messages search "trip" --after 2026-05-01 --before 2026-05-31 wacli --json --read-only messages search "meeting" --chat --limit 100 ``` ### Show a single message ```bash wacli messages show --chat --id wacli --json --read-only messages show --chat --id ``` ### Show context around a message ```bash wacli messages context --chat --id wacli messages context --chat --id --before 10 --after 10 wacli --json --read-only messages context --chat --id --before 3 --after 3 ``` ## Send ### Send text ```bash wacli send text --to +491234567890 --message "hello" wacli send text --to jonna --message "yo" wacli send text --to --message "this is a test" wacli send text --to "Jonna😜" --pick 1 --message "hi" ``` ### Reply to a message ```bash wacli send text --to --reply-to --message "replying here" wacli send text --to --reply-to --reply-to-sender --message "got it" ``` ### Send files ```bash wacli send file --to jonna --file ./pic.jpg wacli send file --to jonna --file ./pic.jpg --caption "look at this" wacli send file --to --file ./clip.mp4 --caption "video test" wacli send file --to --file ./voice.ogg --mime audio/ogg wacli send file --to --file ./report.pdf --filename report-may.pdf wacli send file --to --file ./notes.txt --reply-to wacli send file --to --file ./photo.png --reply-to --reply-to-sender ``` ### React to messages ```bash wacli send react --to --id --reaction "👍" wacli send react --to --id --reaction "🔥" wacli send react --to --id --sender --reaction "😂" ``` ### Remove a reaction ```bash wacli send react --to --id --reaction "" ``` ## Media ### Download media for a message ```bash wacli media download --chat --id wacli media download --chat --id --output ./downloads/ wacli media download --chat --id --output ./downloads/photo.jpg wacli --json media download --chat --id ``` ## Groups ### List groups ```bash 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 ```bash wacli groups refresh wacli groups info --jid wacli --json groups info --jid ``` ### Join / leave / rename groups ```bash wacli groups join --code wacli groups leave --jid wacli groups rename --jid --name "New Group Name" ``` ### Manage participants ```bash wacli groups participants add --jid --user +491111111111 wacli groups participants add --jid --user +491111111111 --user +492222222222 wacli groups participants remove --jid --user +491111111111 wacli groups participants promote --jid --user +491111111111 wacli groups participants demote --jid --user +491111111111 ``` ### Invite links ```bash wacli groups invite link get --jid wacli groups invite link revoke --jid ``` ## History backfill ### Pull older messages from the primary device ```bash wacli history backfill --chat wacli history backfill --chat --requests 3 --count 50 wacli history backfill --chat --requests 10 --count 100 --wait 90s wacli history backfill --chat --idle-exit 10s wacli --json history backfill --chat --requests 2 --count 50 ``` ## Presence ### Typing indicators ```bash wacli presence typing --to wacli presence typing --to --media audio wacli presence paused --to ``` ## Profile ### Set profile picture ```bash wacli profile set-picture ./avatar.jpg wacli profile set-picture ./avatar.png ``` ## Doctor / diagnostics ```bash wacli doctor wacli --json doctor wacli doctor --connect ``` ## Completion scripts ### Bash ```bash wacli completion bash source <(wacli completion bash) wacli completion bash > /etc/bash_completion.d/wacli wacli completion bash --no-descriptions ``` ### Zsh ```bash wacli completion zsh source <(wacli completion zsh) wacli completion zsh > "${fpath[1]}/_wacli" wacli completion zsh --no-descriptions ``` ### Fish ```bash wacli completion fish wacli completion fish | source wacli completion fish > ~/.config/fish/completions/wacli.fish wacli completion fish --no-descriptions ``` ### PowerShell ```powershell wacli completion powershell wacli completion powershell | Out-String | Invoke-Expression wacli completion powershell --no-descriptions ``` ## Version ```bash wacli version wacli --json version ``` ## Handy read-only inspection patterns ```bash wacli --json --read-only auth status wacli --json --read-only chats list --limit 200 wacli --json --read-only messages list --chat --limit 50 wacli --json --read-only messages search "meeting" --limit 100 wacli --json --read-only messages context --chat --id --before 5 --after 5 wacli --json --read-only contacts show --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.