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.
|
||||||
@@ -62,6 +62,10 @@ This published skill came from a setup where:
|
|||||||
|
|
||||||
You may want to tweak these paths and defaults for your own environment.
|
You may want to tweak these paths and defaults for your own environment.
|
||||||
|
|
||||||
|
## Extra examples in this repo
|
||||||
|
|
||||||
|
- [`EXAMPLES.md`](./EXAMPLES.md) — broad command examples covering the current CLI surface
|
||||||
|
|
||||||
## Upstream docs
|
## Upstream docs
|
||||||
|
|
||||||
- Main project: <https://github.com/openclaw/wacli>
|
- Main project: <https://github.com/openclaw/wacli>
|
||||||
|
|||||||
Reference in New Issue
Block a user