Add comprehensive wacli CLI examples
This commit is contained in:
393
EXAMPLES.md
Normal file
393
EXAMPLES.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# 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:
|
||||
|
||||
```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 <chat-jid>
|
||||
wacli --json --read-only chats show --jid <chat-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 <contact-jid>
|
||||
wacli --json --read-only contacts show --jid <contact-jid>
|
||||
```
|
||||
|
||||
### Refresh contacts from the whatsmeow store
|
||||
|
||||
```bash
|
||||
wacli contacts refresh
|
||||
```
|
||||
|
||||
### Aliases
|
||||
|
||||
```bash
|
||||
wacli contacts alias set --jid <contact-jid> --alias jonna
|
||||
wacli contacts alias rm --jid <contact-jid> --alias jonna
|
||||
```
|
||||
|
||||
### Tags
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```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 <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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```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 <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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
wacli send react --to <chat-jid> --id <message-id> --reaction ""
|
||||
```
|
||||
|
||||
## Media
|
||||
|
||||
### Download media for a message
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```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 <group-jid>
|
||||
wacli --json groups info --jid <group-jid>
|
||||
```
|
||||
|
||||
### Join / leave / rename groups
|
||||
|
||||
```bash
|
||||
wacli groups join --code <invite-code>
|
||||
wacli groups leave --jid <group-jid>
|
||||
wacli groups rename --jid <group-jid> --name "New Group Name"
|
||||
```
|
||||
|
||||
### Manage participants
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
wacli presence typing --to <chat-jid>
|
||||
wacli presence typing --to <chat-jid> --media audio
|
||||
wacli presence paused --to <chat-jid>
|
||||
```
|
||||
|
||||
## 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 <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.
|
||||
Reference in New Issue
Block a user