🌊 Wavy 💬

Send WhatsApp messages from your command line, entirely free

Wavy is a lightweight command‑line interface for WhatsApp messaging powered by the whatsmeow library. It lets you authenticate with a QR code, send messages to individuals or groups, verify phone numbers, and browse your group list, all from your terminal.

Key features · Screenshot · Installation · Usage · Data Storage · Viewing WhatsApp Contact Data · Maintenance · Testing · Git Hooks · Releases · License

Key features

• 🔒 QR code authentication Pair your account by scanning a QR code that opens in your image viewer
• 💬 Send messages to contacts Deliver plain text or formatted messages to any registered WhatsApp number
• 👥 Send messages to groups Post updates in your WhatsApp groups by using their group IDs
• ✅ Verify registration status Check if a phone number is registered on WhatsApp before sending a message
• 📋 List your groups Retrieve all your group chats and their IDs to target them easily

Screenshot

Installation

Download Pre-compiled Binaries (Recommended)

The easiest way to install Wavy is to download a pre-compiled binary from the GitHub Releases page:

1. Go to the Releases page
2. Download the appropriate binary for your operating system and architecture:
   • Linux: wavy-linux-amd64 or wavy-linux-arm64
   • macOS: wavy-darwin-amd64 or wavy-darwin-arm64
   • Windows: wavy-windows-amd64.exe
3. Make the downloaded file executable (Linux/macOS):

   chmod +x wavy-linux-amd64
   # Or for macOS:
   # chmod +x wavy-darwin-amd64

4. Move the binary to a directory in your PATH (optional, for easier access):

   # Linux/macOS:
   sudo mv wavy-linux-amd64 /usr/local/bin/wavy
   # For macOS with Apple Silicon:
   # sudo mv wavy-darwin-arm64 /usr/local/bin/wavy

Building from Source

This project uses Mage for its build system.

1. Install Mage (if not already installed):

   go install github.com/magefile/mage@latest

2. Build the tool:

   mage build

   This will create bin/wavy executable.

3. Install the tool system-wide (optional):

   mage install

   This will:

   • Copy the binary to /usr/local/bin/wavy
   • Create the required config directories at ~/.config/wavy/ and ~/.local/share/wavy/

Usage

WhatsApp connection setup

1. Open your terminal and run:

   wavy setup

2. A QR code will be generated and displayed in your image viewer.

3. On your phone, open WhatsApp and navigate to Settings > Linked Devices > Link a Device

4. Scan the QR code on your computer screen.

5. Once pairing is successful, WhatsApp will confirm the new device is connected. You're now authenticated and ready to send messages.

6. In your terminal, press Ctrl+C to exit the setup script.

Checking if a number is on WhatsApp

wavy check +1234567890

Or using flags:

wavy check --phone +1234567890

Listing your WhatsApp groups

wavy groups

This will show all groups you're a member of, including their group IDs which you need for sending messages to groups.

Sending Messages

To a contact:

wavy send +1234567890 "Hello from Wavy CLI"

Or using flags:

wavy send --to +1234567890 --msg "Hello from Wavy CLI"

To a group:

wavy send [email protected] "Hello group from Wavy CLI"

You must use the exact group ID from the wavy groups command.

Additional options:

• --debug - Enable verbose debug output
• --wait N - Wait N seconds for message confirmation (default: 5)

Example:

wavy send --to +1234567890 --msg "Hello with debug" --debug --wait 10

Data Storage

All wavy data is stored according to the XDG Base Directory Specification:

• Configuration: ~/.config/wavy/
• Data (including WhatsApp session): ~/.local/share/wavy/

Viewing WhatsApp Contact Data

The WhatsApp session data is stored in a SQLite database at ~/.local/share/wavy/client.db. You can inspect this database to view your contacts and other information:

Installing SQLite CLI

# For Debian/Ubuntu
sudo apt install sqlite3

# For Fedora
sudo dnf install sqlite

# For macOS
brew install sqlite

Viewing Contact Data

1. Open the database:

   sqlite3 ~/.local/share/wavy/client.db

2. View available tables:

   .tables

3. View your contacts:

   SELECT * FROM whatsmeow_contacts;

4. View specific contact information:

   SELECT jid, name, first_name, push_name FROM whatsmeow_contacts;

5. Count your contacts:

   SELECT COUNT(*) FROM whatsmeow_contacts;

6. Find a specific contact by name:

   SELECT * FROM whatsmeow_contacts WHERE name LIKE '%John%';

7. Exit SQLite:

   .exit
   

Using SQLite in Script Mode

You can also query the database directly from the command line:

sqlite3 ~/.local/share/wavy/client.db "SELECT jid, name FROM whatsmeow_contacts"

Maintenance

Additional Mage commands available:

• mage clean - Remove build artifacts
• mage uninstall - Completely remove wavy from your system
• mage test - Run tests
• mage check - Run linters and static analysis

Testing

This project includes unit tests to verify functionality. You can run tests using Mage:

Running Basic Tests

Run all tests:

mage test

Running Tests with Verbose Output

For more detailed test results:

mage testVerbose

Generate Test Coverage Report

Generate coverage report (HTML format):

mage testCoverage

This creates a coverage report at coverage/coverage.html that you can open in a browser.

Git Hooks

This project uses Lefthook to enforce code quality checks before commits and pushes.

Setup

1. Install Lefthook:

   go install github.com/evilmartians/lefthook@latest

2. Install the Git hooks:

   lefthook install

What it does

• Runs go vet, gofmt, and go test on commit
• Runs go test on push

The full configuration is available in the lefthook.yml file at the project root.

You can also run the hooks manually:

lefthook run pre-commit
lefthook run pre-push

Running All Tasks

Run formatting, static analysis, tests and build in one command:

mage all

Releases

Wavy is available as pre-compiled binaries for various operating systems and architectures. You can download the latest version from the Releases page.

The following platforms are supported:

• Linux: amd64 and arm64 architectures
• macOS (Darwin): amd64 (Intel) and arm64 (Apple Silicon) architectures
• Windows: amd64 architecture

Version Command

You can check which version of Wavy you're running with:

wavy version

Release Process

If you're a contributor interested in the release process for this project, please see the Release Process documentation for details on how we version and build releases.

License

Licensed under the MIT License. See the LICENSE file for details.