# wacli-skill

Agent skill for using the local `wacli` WhatsApp CLI instead of browser automation.

`wacli` is a scriptable WhatsApp client built on [`whatsmeow`](https://github.com/tulir/whatsmeow). It pairs as a linked WhatsApp Web device, mirrors messages into a local SQLite store, and supports offline search, sending, and chat/contact management from the command line.

> Third-party tool. Uses the WhatsApp Web protocol via `whatsmeow`. Not affiliated with WhatsApp.

## Why this skill exists

This skill gives an agent a clean, local path for WhatsApp work without poking at browser DOM junk.

Good fits:
- QR pairing and auth status checks
- one-shot or follow-mode sync
- offline message search and context lookups
- sending text, files, reactions, stickers, and voice notes
- chat and contact inspection from the local store

## Contents

- `SKILL.md` — skill instructions, safe defaults, and command patterns
- `scripts/wacli-local.sh` — tiny wrapper that execs the local `wacli` binary

## Highlights from `wacli`

- **Auth + sync** — QR pairing, one-shot sync, or long-running follow mode
- **Offline message store** — local SQLite history with FTS search
- **Sending** — text, replies, mentions, files, stickers, voice notes, reactions
- **History backfill** — best-effort older-message requests from the primary device
- **Scriptable output** — `--json` for machine-readable reads and automation-friendly flows
- **Diagnostics + safety** — `doctor`, read-only mode, lock handling, bounded local behavior

## Quick start

```bash
# Pair (shows QR), then bootstrap sync
wacli auth

# Keep syncing after auth
wacli sync --follow

# Inspect chats and recent messages
wacli --json --read-only chats list --limit 50
wacli --json --read-only messages list --chat <chat-jid> --limit 20

# Search locally stored messages
wacli --json --read-only messages search "meeting"

# Send
wacli send text --to 1234567890 --message "hello"
```

Recipients can be a JID, phone number, or synced contact/group/chat name. If a name is ambiguous, use a JID or the CLI selection flags supported by `wacli`.

## Local assumptions

This published skill came from a setup where:
- `wacli` is installed and available on `PATH`
- the default store is `/root/.local/state/wacli`
- agents should prefer `--json --read-only` for inspection work

You may want to tweak these paths and defaults for your own environment.

## Upstream docs

- Main project: <https://github.com/openclaw/wacli>
- Full documentation: <https://wacli.sh>

## Source

Published from Luna's local OpenClaw workspace.