Quickstart
Five minutes from a clean machine to authenticated sync, search, and send. For deeper reading, follow the links at the bottom of each step.
#1. Install
brew install steipete/tap/wacli
wacli --versionOther options (release archives, source builds, GCC 15 notes) are documented on Install.
#2. Pair as a linked device
wacli authauth prints a QR code in your terminal. On your phone, open WhatsApp → Linked devices → Link a device, scan the QR, and approve. As soon as pairing succeeds, auth immediately starts the initial sync — keep it running until it idles out or press Ctrl+C once it has caught up.
If the QR does not scan, try --qr-format text (numeric fallback) or pair via phone-number code with --phone +15551234567.
Refresh tokens last as long as the linked device stays linked on your phone. Unlinking from the phone (or
wacli auth logout) ends the session and requires a fresh QR.
Verify:
wacli auth status#3. Keep the store warm
wacli sync --followsync never shows a QR; it requires a previously paired session and runs until you stop it. --once exits after one idle window; --follow reconnects on errors. Both honor --max-messages / --max-db-size (and the WACLI_SYNC_MAX_* env equivalents) so the local store stays bounded.
See Sync for refresh-contacts/refresh-groups, --download-media, and the idle-exit knobs.
#4. Search and read
# Full-text search (FTS5 when the binary was built with -tags sqlite_fts5; LIKE otherwise)
wacli messages search "meeting"
# Search media-bearing messages
wacli messages search "meeting" --has-media
# List recent messages from a chat, oldest first
wacli messages list --chat 1234567890@s.whatsapp.net --asc
# Show a single message
wacli messages show --chat 1234567890@s.whatsapp.net --id <message-id>
# Show context around a message
wacli messages context --chat 1234567890@s.whatsapp.net --id <message-id> --before 5 --after 5--json produces a stable envelope; --full keeps full IDs in tables. See Messages for every filter.
#5. Send a message
# Send a text message by phone number, JID, or synced contact/group/chat name
wacli send text --to mom --message "hello"
# Send a quoted reply
wacli send text --to 1234567890 --message "replying" --reply-to <message-id>
# Send a file with a caption
wacli send file --to 1234567890 --file ./pic.jpg --caption "hi"
# Send a 512x512 WebP sticker
wacli send sticker --to 1234567890 --file ./sticker-512.webp
# Send a native voice note (OGG/Opus)
wacli send voice --to 1234567890 --file ./voice.ogg
# React (omit --reaction for the default thumbs-up; use --reaction "" to clear)
wacli send react --to 1234567890 --id <message-id> --reaction "🎉"Recipient resolution and disambiguation (--pick N, ambiguous-name prompts), link-preview behavior, and post-send waits are documented in Send.
#6. Backfill older history (optional, best-effort)
sync only stores what WhatsApp Web pushes. To request older messages for a specific chat from your primary device (your phone), use:
wacli history backfill --chat 1234567890@s.whatsapp.net --requests 10 --count 50The phone must be online. WhatsApp may not return full history. See History for limits and patterns (loop over chats with jq, recommended --count/--requests ceilings).
#7. Diagnostics and safety
wacli doctor
wacli doctor --connect
# Read-only mode for agents / sandboxes
wacli --read-only messages search "invoice"
WACLI_READONLY=1 wacli send text --to mom --message "hi" # exits with a clear errordoctor checks the store, schema, FTS5 availability, and (with --connect) live connectivity. See Doctor.
#8. Shell completion (optional)
wacli completion bash >> ~/.bash_completion
wacli completion zsh > "${fpath[1]}/_wacli"
wacli completion fish > ~/.config/fish/completions/wacli.fish#Where next
- Overview — global flags, store model, full command map.
- Send — every recipient form, replies, reactions, mentions, link previews.
- Groups — list, refresh, info, rename, participants, invite links.
- Spec — design notes, storage layout, locking model, non-goals.
- Doctor — self-checks and connectivity probe.