whatsapp-read-cli

name	whatsapp-read-cli
description	Use when an agent needs to answer questions by reading a user's local macOS WhatsApp data through the whatsapp-read-cli tool. Trigger for tasks like finding chats, unread chats, messages in a chat, contacts, calls, local WhatsApp search, or safely using the CLI without contacting WhatsApp servers.

WhatsApp Read CLI

Use whatsapp-read-cli as a read-only local data source for WhatsApp on macOS.

Safety Rules

• Never contact WhatsApp servers.
• Never mark messages read, send messages, delete data, edit data, sync data, or imply that the CLI can modify WhatsApp state.
• Prefer normal commands over debug.
• Use debug query only when normal commands cannot answer the question.
• If using debug query, run only a single SELECT; never attempt write SQL.
• Avoid unnecessary large message dumps.

Setup Check

If the binary may not be installed, first try:

whatsapp-read-cli info

If missing and the repo is available, install from the repo root:

cargo install --path . --locked

If auto-detection reads the wrong WhatsApp instance, use:

whatsapp-read-cli --root "/path/to/group.net.whatsapp.WhatsApp.shared" info

Output Formats

Default output is human-readable. For parsing, use:

whatsapp-read-cli --format json ...
whatsapp-read-cli --format tsv ...

Prefer json when you need structured post-processing. Prefer small --limit values while exploring.

Common Tasks

Check Available Data

whatsapp-read-cli info

Use this to confirm the detected root, read-only mode, and counts for chats, unread chats, messages, contacts, and calls.

Find Chats

whatsapp-read-cli chats --limit 50
whatsapp-read-cli chats --unread --limit 50
whatsapp-read-cli chats --limit 50 --offset 50

Use --limit 0 only when the user explicitly needs all rows.

Read Messages

messages always requires --chat.

whatsapp-read-cli messages --chat 123 --limit 50
whatsapp-read-cli messages --chat "Alice" --limit 50
whatsapp-read-cli messages --chat 123 --unread

--chat accepts a chat id from chats, or a name/JID substring only when it matches exactly one chat. If multiple chats match, use the printed candidates and rerun with the exact chat id.

Search Messages

whatsapp-read-cli search "invoice" --limit 50
whatsapp-read-cli search "invoice" --chat 123 --limit 50

Search is global by default because the user gave an explicit search term. Add --chat when the user asks about a specific conversation.

Contacts And Calls

whatsapp-read-cli contacts --limit 100
whatsapp-read-cli calls --limit 100

Use --offset for pagination.

Debug Escape Hatch

Only use debug commands for troubleshooting or schema inspection:

whatsapp-read-cli debug dbs
whatsapp-read-cli debug tables --db chat
whatsapp-read-cli debug schema --db chat ZWAMESSAGE
whatsapp-read-cli debug query --db chat "SELECT Z_PK, ZTEXT FROM ZWAMESSAGE LIMIT 10"

Normal user questions should usually be answered with info, chats, messages, contacts, calls, or search.