Commands

WhatsApp wacli Skill

Binary location: ./skills/whatsapp-wacli-mac/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-mac/tools/wacli && echo "ready" || echo "needs install"

If it prints needs install, build or install it using one of the methods below, then proceed.

Option A: Homebrew (recommended — no Go toolchain required)

brew install steipete/tap/wacli
cp "$(brew --prefix)/bin/wacli" ./skills/whatsapp-wacli-mac/tools/wacli
chmod +x ./skills/whatsapp-wacli-mac/tools/wacli

Option B: Build from source (requires Go 1.25+ with CGO enabled)

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-mac/tools/wacli \
  && chmod +x ./skills/whatsapp-wacli-mac/tools/wacli \
  && rm -rf /tmp/wacli-src /tmp/wacli-bin

Note: builds natively for the current architecture (darwin/arm64 on Apple Silicon).

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-mac/tools/wacli chats list or contacts search to find JIDs.

Authentication Flow

The skill uses a .authenticated marker file in the skill directory (./skills/whatsapp-wacli-mac/.authenticated) to track authentication state and optimize subsequent calls.

Authentication Decision Flow

Before executing any wacli command, follow this logic:

1. Check for .authenticated marker (test -f ./skills/whatsapp-wacli-mac/.authenticated)
   • If EXISTS: Proceed directly to execute the requested command
   • If command fails with auth error: Remove the marker file (rm -f ./skills/whatsapp-wacli-mac/.authenticated) and go to Step 2
2. If .authenticated does NOT exist: Check auth status via wacli

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

   • If status shows authenticated: Create marker file and execute command

     touch ./skills/whatsapp-wacli-mac/.authenticated
     # then execute requested command

   • If status shows NOT authenticated: Go to Step 3
3. Full authentication flow: Run interactive auth and create marker on success

   ./skills/whatsapp-wacli-mac/tools/wacli auth
   # User scans QR code...
   # On success:
   touch ./skills/whatsapp-wacli-mac/.authenticated

Complete Auth Logic Example

# Step 1: Check if .authenticated marker exists
result = exec({"command": "test -f ./skills/whatsapp-wacli-mac/.authenticated && echo 'marker_exists' || echo 'no_marker'"})

if result contains 'marker_exists':
    # Proceed with command
    result = exec({"command": "./skills/whatsapp-wacli-mac/tools/wacli <REQUESTED_COMMAND>"})
    
    # If command fails due to auth issues
    if result contains 'unauthorized' or 'not authenticated':
        exec({"command": "rm -f ./skills/whatsapp-wacli-mac/.authenticated"})
        # Fall through to check status
    else:
        # Command succeeded, return result
        return result

# Step 2: Check actual auth status
status = exec({"command": "./skills/whatsapp-wacli-mac/tools/wacli auth status --json"})

if status contains '"status": "authenticated"':
    # User is already authenticated, create marker and execute
    exec({"command": "touch ./skills/whatsapp-wacli-mac/.authenticated"})
    result = exec({"command": "./skills/whatsapp-wacli-mac/tools/wacli <REQUESTED_COMMAND>"})
    return result
else:
    # Step 3: Need to authenticate
    print("Please scan the QR code with WhatsApp to authenticate...")
    auth_result = exec({"command": "./skills/whatsapp-wacli-mac/tools/wacli auth", "timeout": 120})
    
    # Verify auth succeeded
    verify = exec({"command": "./skills/whatsapp-wacli-mac/tools/wacli auth status --json"})
    if verify contains '"status": "authenticated"':
        exec({"command": "touch ./skills/whatsapp-wacli-mac/.authenticated"})
        # Now execute the requested command
        result = exec({"command": "./skills/whatsapp-wacli-mac/tools/wacli <REQUESTED_COMMAND>"})
        return result
    else:
        return "Authentication failed. Please try again."

Authentication Management

Check auth status:

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

Logout (also removes .authenticated marker):

./skills/whatsapp-wacli-mac/tools/wacli auth logout && rm -f ./skills/whatsapp-wacli-mac/.authenticated

Diagnostics:

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

Sending Messages

Text message

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

File (image/video/audio/document)

./skills/whatsapp-wacli-mac/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-mac/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-mac/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-mac/tools/wacli messages show --chat <JID> --id <MESSAGE_ID>

Show context around a message

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

Chats

List chats

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

Search chats by name/number

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

Show a specific chat

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

Contacts

Search contacts

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

Show a specific contact

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

Set a local alias for a contact

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

Remove an alias

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

Refresh contacts from session store

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

Groups

List groups

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

Refresh groups (live from WhatsApp)

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

Get group info

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

Rename a group

./skills/whatsapp-wacli-mac/tools/wacli groups rename --jid <GROUP_JID> --name "New Name"

Join a group by invite code

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

Leave a group

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

Manage group invite links

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

Manage group participants

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

Sync

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

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

Continuous sync (keeps running)

./skills/whatsapp-wacli-mac/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-mac/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-mac/tools/wacli media download --chat <JID> --id <MESSAGE_ID>

Optional: --output /path/to/save

Global Flags (available on all commands)

Environment Variables

Exec Tool Examples

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

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

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

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

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

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

Important Notes

1. Phone numbers: digits only, no + prefix — e.g., [PHONE_NUMBER] not +[PHONE_NUMBER]
2. Auth flow: The skill follows a three-step authentication flow (marker check → status check → interactive auth) to optimize subsequent calls
3. .authenticated marker file — stored in ./skills/whatsapp-wacli-mac/.authenticated; created after successful auth to bypass checks on future calls
4. Auth failure handling — If a command fails due to auth issues, the marker is automatically removed and the flow restarts
5. Primary device must be online — phone needs WhatsApp running for sync/send
6. Store lock — only one wacli process can run at a time. If you get a lock error, wait or kill the other process
7. Rate limits — respect WhatsApp's sending limits
8. Third-party tool — not affiliated with WhatsApp/Meta; uses WhatsApp Web protocol