From 774777401307e8e07f39d6917f6132e58ccbff84 Mon Sep 17 00:00:00 2001 From: Luna Date: Wed, 6 May 2026 10:47:40 +0200 Subject: [PATCH] Expand README with wacli overview and usage --- README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 37c6303..462a92b 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,71 @@ 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 and command patterns +- `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 --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: +- Full documentation: + ## Source Published from Luna's local OpenClaw workspace.