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:

```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.