wa-cli

README

wa-cli

A WhatsApp client for your terminal, built in Go on top of whatsmeow.

Status: v1.0.0 — stable and cross-platform, with a couple of documented known limitations rather than zero known bugs; see ROADMAP.md for exactly what's done and what's known to still need work.

Docs: browse this repo's docs as a site at codebyoketch.github.io/wa-cli, or generated API docs at pkg.go.dev/github.com/codebyoketch/wa-cli.

Why

Scriptable, fast, terminal-first WhatsApp: send and receive messages, manage chats/contacts/groups/media, all from the command line — with --json output for scripting and automation, and a full-screen TUI (wa, no subcommand) for everyday use.

Install

Prebuilt binaries (Linux/macOS/Windows, amd64/arm64) are on the Releases page. Download the archive for your platform, extract it, and put the wa binary somewhere on your PATH.

# Homebrew (macOS/Linux)
brew install codebyoketch/tap/wa-cli

# Scoop (Windows)
scoop bucket add wa-cli https://github.com/codebyoketch/scoop-bucket
scoop install wa-cli

# Docker
docker run -it -v wa-data:/data ghcr.io/codebyoketch/wa-cli:latest login

Homebrew on Linux: if you don't already have brew, it isn't preinstalled — get it from brew.sh first (/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"). The installer prints a "Next steps" section with a PATH line you need to run before brew works in your current shell — usually eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)", added to ~/.bashrc (or your shell's equivalent) so it persists across terminals. It also asks for build-essential and bubblewrap via apt, needed to install some formulae on Linux.

Or with Go 1.25+ installed:

go install github.com/codebyoketch/wa-cli@latest

Or build from source:

git clone https://github.com/codebyoketch/wa-cli.git
cd wa-cli
make build   # binary at ./bin/wa

For quick local iteration without a build step, use go run . in place of wa anywhere below.

Getting started

wa login              # scan the QR code with WhatsApp on your phone
wa status             # confirm you're logged in
wa chat list           # sync and list your chats

Run wa with no subcommand to open the full-screen terminal UI instead of using individual commands.

Usage

Chats

wa chat list [--no-sync]        # list chats, most recent first
wa chat search <query>          # search chats by name
wa chat info <jid-or-name>      # details for one chat
wa chat open <jid-or-name>      # show local message history
wa chat send <recipient> <message...>
wa chat reply <recipient> <message-ref> <message...>
wa chat forward <from-chat> <message-ref> <to-recipient>
wa chat mute / unmute <chat>    # suppress desktop notifications per chat

Receiving

wa watch                        # long-running: print incoming messages live

Contacts

wa contact list
wa contact search <query>
wa contact info <name-or-jid>

Groups

wa group list
wa group info <name-or-jid>
wa group create <name> <participant...>
wa group add / remove <group> <participant...>

Media

wa media send image/video/audio/document/sticker <recipient> <file>
wa media download <chat> <message-ref> [output-path]
wa media list <chat>            # media messages in a chat's local history

image send/download are verified against a real account; the other media types are implemented but not yet confirmed end-to-end — see Phase 8 in ROADMAP.md.

Config

wa config get [key]             # print all settings, or one
wa config set <key> <value>     # change and save one setting
wa config edit                  # open config.json in $EDITOR
wa config init                  # write out defaults

Extensions

wa extension install <git-url>
wa extension list
wa extension run <name> [-- args...]
wa extension remove <name>

Other

wa status                       # login status
wa version
wa completion bash|zsh|fish|powershell

JSON output

Every list/read command above (chat list/search/info/open, contact list/search/info, group list/info, media list, status, extension list) supports --json for scripting:

wa chat list --json | jq '.[] | .name'

Set it as the default instead of passing the flag every time:

wa config set jsonOutput true

Notifications

Desktop notifications fire from wa watch and the TUI when a new message arrives (not from one-shot commands). Configurable via wa config set:

wa config set notifyEnabled true|false
wa config set notifyGroups true|false        # group chats opt-in separately from DMs
wa config set notifyShowPreview true|false   # include message text in the notification
wa chat mute <chat>                          # suppress notifications for one chat

Development

make build   # compile ./bin/wa
make test    # go test ./...
make lint    # golangci-lint run
make fmt     # gofmt -w .

Roadmap

See ROADMAP.md for the full phase-by-phase plan, what's done, what's in progress, and known issues.

Architecture

See ARCHITECTURE.md for a map of the codebase — package layout and how the pieces fit together.

Examples

See docs/EXAMPLES.md for worked examples: scripting with --json, a daily unread-chats digest, piping wa watch, sending from a script without hitting an interactive prompt, exporting chat history, and writing a minimal extension.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for how to report vulnerabilities.

License

MIT

Documentation

Overview

wa-cli is a WhatsApp client for your terminal, built on go.mau.fi/whatsmeow. It links as a WhatsApp Web device (no browser needed) and gives you chats, contacts, groups, and media send/receive from the command line — plus a split-pane TUI (run wa with no subcommand), --json output for scripting, and a plugin system (wa extension).

See README.md for installation and a full command list, ARCHITECTURE.md for how the pieces fit together, and docs/EXAMPLES.md for worked scripting examples. The actual command implementations live in the cmd package; this file just wires up Cobra's entrypoint.