# wacli
> Third-party WhatsApp CLI for message sync, search, and sending

## Summary
Third-party WhatsApp CLI using the Web protocol for local message synchronization, offline full-text search, text/file sending, and group management. Stores data locally with JSON output for scripting.

## Capabilities
- Authenticate via interactive QR code display and initial sync
- Continuous message synchronization loop with local SQLite storage
- Fast offline full-text search across all synced messages
- History backfill to retrieve older messages from the primary device
- Send text messages and files with optional captions
- List and manage groups
- JSON output mode for scripting and agent integration
- Diagnostic doctor command for troubleshooting

## When to Use
- An AI agent or script needs to send or read WhatsApp messages
- Searching through WhatsApp message history from the terminal
- Archiving WhatsApp conversations locally for backup or analysis
- Automating WhatsApp notifications from scripts or CI pipelines

## When NOT to Use
- The primary WhatsApp device is offline (needed for backfill)
- WhatsApp's Terms of Service prohibit your use case
- You need real-time message streaming (sync is best-effort)
- Working with iMessage or other non-WhatsApp services

## Usage Patterns
### Authenticate and initial sync
```
wacli auth
```
Displays QR code for linking, then performs initial message sync

### Continuous sync
```
wacli sync --follow
```
Runs a continuous sync loop capturing new messages

### Search messages
```
wacli messages search "meeting tomorrow" --json
```
Searches synced messages for the given query

### Send a text message
```
wacli send text --to "+1234567890" --body "Hello!"
```
Sends a text message to the specified number

### Send a file
```
wacli send file --to "+1234567890" --path ./document.pdf --caption "Here you go"
```
Sends a file with an optional caption

### List groups
```
wacli groups list --json
```
Lists all WhatsApp groups in JSON format

## Input / Output
- **stdin**: Not typically used
- **stdout**: Human-readable text or JSON (with --json flag)
- **stderr**: Status and error messages

## Installation
- **homebrew**: `brew install steipete/tap/wacli`
- **source**: `go build -tags sqlite_fts5 -o ./dist/wacli ./cmd/wacli`

## Related Tools
- [imsg](/tools/imsg) (alternative): imsg provides similar messaging CLI capabilities for Apple iMessage

---
Source: https://littlescripts.sh/tools/wacli
