agentleFS
Sign inStart free
tsukhanitsukhani/jclaw/skills/whatsapp-wacli-linux/SKILL.md

whatsapp-wacli-linux

Skill42 starsChanged 8 days agoMITView on GitHub

Use wacli (WhatsApp CLI) to sync, search, send messages, manage contacts/groups, and backfill chat history. REQUIRES AUTHENTICATION FIRST. Linux x86_64 binary.

  • Deletes or force-pushes
  • Installs packages

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Always use this path when invoking commands.

    line 16
  2. Very specific:

    If it prints needs install, build it from source:

    line 28
  3. Very specific:

    Use ./skills/whatsapp-wacli-linux/tools/wacli chats list or contacts search to find JIDs.

    line 57

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

WhatsApp wacli Skill

Binary location: ./skills/whatsapp-wacli-linux/tools/wacli

Always use this path when invoking commands.

Bootstrap (First-time setup)

Before running any wacli command, check whether the binary is present:

test -x ./skills/whatsapp-wacli-linux/tools/wacli && echo "ready" || echo "needs install"

If it prints needs install, build it from source:

# Ensure build dependencies are available
which go || (echo "Go 1.25+ is required — install from https://go.dev/dl/" && exit 1)
which gcc || apt-get install -y gcc 2>/dev/null || yum install -y gcc 2>/dev/null

git clone --depth 1 https://github.com/steipete/wacli /tmp/wacli-src \
  && cd /tmp/wacli-src \
  && CGO_ENABLED=1 go build -tags sqlite_fts5 -o /tmp/wacli-bin ./cmd/wacli \
  && cp /tmp/wacli-bin ./skills/whatsapp-wacli-linux/tools/wacli \
  && chmod +x ./skills/whatsapp-wacli-linux/tools/wacli \
  && rm -rf /tmp/wacli-src /tmp/wacli-bin

Note: CGO is required (SQLite dependency). gcc must be present. Builds natively for linux/amd64.

Once the binary is present, proceed to Authentication below.

CRITICAL: Phone Number Format

Phone numbers must be digits only with country code, without the + prefix:

  • Correct: [PHONE_NUMBER]
  • Wrong: +[PHONE_NUMBER] (causes timeout/resolution errors)

For groups, use JID format: [PHONE_NUMBER]@g.us

Use ./skills/whatsapp-wacli-linux/tools/wacli chats list or contacts search to find JIDs.

Authentication (Required First)

./skills/whatsapp-wacli-linux/tools/wacli auth

This displays a QR code. The user must scan it with WhatsApp (Settings > Linked Devices > Link a Device). The command stays running while waiting for the scan and initial sync. Use a timeout of at least 120 seconds.

Check auth status:

./skills/whatsapp-wacli-linux/tools/wacli auth status

Logout:

./skills/whatsapp-wacli-linux/tools/wacli auth logout

Diagnostics:

./skills/whatsapp-wacli-linux/tools/wacli doctor

Sending Messages

Text message

./skills/whatsapp-wacli-linux/tools/wacli send text --to [PHONE_NUMBER] --message "Hello!"

File (image/video/audio/document)

./skills/whatsapp-wacli-linux/tools/wacli send file --to [PHONE_NUMBER] --file /path/to/photo.jpg

Optional flags:

  • --caption "Description" — caption for images/videos/documents
  • --filename report.pdf — override the display filename
  • --mime image/jpeg — override auto-detected MIME type

Messages

List messages in a chat

./skills/whatsapp-wacli-linux/tools/wacli messages list --chat [PHONE_NUMBER]@s.whatsapp.net --limit 20

Optional: --after 2025-01-01 --before 2025-12-31

Search messages (full-text)

./skills/whatsapp-wacli-linux/tools/wacli messages search "keyword" --limit 20

Optional filters:

  • --chat <JID> — restrict to a specific chat
  • --from <JID> — restrict to a specific sender
  • --after 2025-01-01 / --before 2025-12-31 — date range
  • --type image|video|audio|document — media type filter

Show a specific message

./skills/whatsapp-wacli-linux/tools/wacli messages show --chat <JID> --id <MESSAGE_ID>

Show context around a message

./skills/whatsapp-wacli-linux/tools/wacli messages context --chat <JID> --id <MESSAGE_ID> --before 5 --after 5

Chats

List chats

./skills/whatsapp-wacli-linux/tools/wacli chats list --limit 20

Search chats by name/number

./skills/whatsapp-wacli-linux/tools/wacli chats list --query "name or number"

Show a specific chat

./skills/whatsapp-wacli-linux/tools/wacli chats show --jid [PHONE_NUMBER]@s.whatsapp.net

Contacts

Search contacts

./skills/whatsapp-wacli-linux/tools/wacli contacts search "name" --limit 20

Show a specific contact

./skills/whatsapp-wacli-linux/tools/wacli contacts show --jid [PHONE_NUMBER]@s.whatsapp.net

Set a local alias for a contact

./skills/whatsapp-wacli-linux/tools/wacli contacts alias set --jid [PHONE_NUMBER]@s.whatsapp.net --alias "Mom"

Remove an alias

./skills/whatsapp-wacli-linux/tools/wacli contacts alias rm --jid [PHONE_NUMBER]@s.whatsapp.net

Refresh contacts from session store

./skills/whatsapp-wacli-linux/tools/wacli contacts refresh

Groups

List groups

./skills/whatsapp-wacli-linux/tools/wacli groups list

Refresh groups (live from WhatsApp)

./skills/whatsapp-wacli-linux/tools/wacli groups refresh

Get group info

./skills/whatsapp-wacli-linux/tools/wacli groups info --jid <GROUP_JID>

Rename a group

./skills/whatsapp-wacli-linux/tools/wacli groups rename --jid [PHONE_NUMBER]@g.us --name "New Name"

Join a group by invite code

./skills/whatsapp-wacli-linux/tools/wacli groups join --code <INVITE_CODE>

Leave a group

./skills/whatsapp-wacli-linux/tools/wacli groups leave --jid <GROUP_JID>

Manage group invite links

./skills/whatsapp-wacli-linux/tools/wacli groups invite --jid <GROUP_JID>

Manage group participants

./skills/whatsapp-wacli-linux/tools/wacli groups participants --jid <GROUP_JID>

Sync

One-time sync (sync until idle, then exit)

./skills/whatsapp-wacli-linux/tools/wacli sync --once

Continuous sync (keeps running)

./skills/whatsapp-wacli-linux/tools/wacli sync --follow

Optional flags:

  • --download-media — download media files during sync
  • --refresh-contacts — refresh contacts from session store
  • --refresh-groups — refresh group list from WhatsApp
  • --idle-exit 30s — exit after idle period (with --once)

History Backfill

Request older messages for a specific chat from the primary device:

./skills/whatsapp-wacli-linux/tools/wacli history backfill --chat <JID> --requests 10 --count 50

Flags:

  • --count 50 — messages per request (recommended: 50)
  • --requests 10 — number of requests to attempt
  • --wait 1m — time to wait per request for a response
  • --idle-exit 5s — exit after idle

Note: Best-effort. Primary device must be online. WhatsApp may not return full history.

Media

Download media from a message

./skills/whatsapp-wacli-linux/tools/wacli media download --chat <JID> --id <MESSAGE_ID>

Optional: --output /path/to/save

Global Flags (available on all commands)

FlagPurpose
--jsonOutput JSON instead of human-readable text
--store DIRCustom store directory (default: ~/.wacli)
--timeout 5mCommand timeout for non-sync commands

Environment Variables

VariablePurpose
WACLI_DEVICE_LABELLinked device label shown in WhatsApp
WACLI_DEVICE_PLATFORMOverride device platform (default: CHROME)

Exec Tool Examples

# Authenticate (use timeout=120 for QR scan)
exec({"command": "./skills/whatsapp-wacli-linux/tools/wacli auth", "timeout": 120})

# Send text (NO + prefix on phone number)
exec({"command": "./skills/whatsapp-wacli-linux/tools/wacli send text --to [PHONE_NUMBER] --message 'Hello!'"})

# Send file
exec({"command": "./skills/whatsapp-wacli-linux/tools/wacli send file --to [PHONE_NUMBER] --file /tmp/report.pdf --caption 'Monthly report'"})

# Search messages (JSON for parsing)
exec({"command": "./skills/whatsapp-wacli-linux/tools/wacli messages search 'invoice' --json"})

# List recent chats
exec({"command": "./skills/whatsapp-wacli-linux/tools/wacli chats list --limit 10"})

# One-time sync
exec({"command": "./skills/whatsapp-wacli-linux/tools/wacli sync --once", "timeout": 60})

# Check auth status
exec({"command": "./skills/whatsapp-wacli-linux/tools/wacli auth status"})

Important Notes

  1. Phone numbers: digits only, no + prefix — e.g., [PHONE_NUMBER] not +[PHONE_NUMBER]
  2. Auth required first — run auth and scan QR before any other command
  3. Primary device must be online — phone needs WhatsApp running for sync/send
  4. Store lock — only one wacli process can run at a time. If you get a lock error, wait or kill the other process
  5. Rate limits — respect WhatsApp's sending limits
  6. Third-party tool — not affiliated with WhatsApp/Meta; uses WhatsApp Web protocol

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free