From 0502c9f4edd46ec1f355387a6d8e1a7fab68aaa4 Mon Sep 17 00:00:00 2001 From: Luna Date: Wed, 6 May 2026 10:51:02 +0200 Subject: [PATCH] Add comprehensive wacli CLI examples --- EXAMPLES.md | 393 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 + 2 files changed, 397 insertions(+) create mode 100644 EXAMPLES.md diff --git a/EXAMPLES.md b/EXAMPLES.md new file mode 100644 index 0000000..e6a83a1 --- /dev/null +++ b/EXAMPLES.md @@ -0,0 +1,393 @@ +# 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. diff --git a/README.md b/README.md index 462a92b..6f9b194 100644 --- a/README.md +++ b/README.md @@ -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. +## Extra examples in this repo + +- [`EXAMPLES.md`](./EXAMPLES.md) — broad command examples covering the current CLI surface + ## Upstream docs - Main project: