GOWA CLI

WhatsApp from your terminal. Built for AI agents and developers.

🇺🇸 English | 🇧🇷 Português | 🇪🇸 Español | 🇮🇳 हिन्दी

Send messages, read chats, search contacts, manage groups — all from a single binary.
No Docker. No servers. No runtime dependencies. Just gowa.

---

For AI Agents

Quick start for Claude Code, Codex, Cursor, Gemini, Copilot, Windsurf, and OpenCode.

Install + configure your agent in one command:

curl -fsSL https://raw.githubusercontent.com/murilloimparavel/gowa-cli/main/scripts/install-skill.sh | bash

Agent quick start:

gowa context --json                                          # get full system state
gowa daemon status --json                                    # check connection
gowa chat list --json                                        # list chats
gowa chat search "keyword" --json                            # full-text search
gowa contact search "Alice" --json                           # find contact
gowa send text --to 5511999999999 "Hello" --json --accept-risk  # send message

Resources:

• SKILL.md — Full agent skill manifest with all commands and safety constraints
• gowa.tools.json — Machine-readable tool schema (34 KB, every command/flag/exit code)
• ROADMAP v1.1.0 — Future agentic features (Webhooks, Spawners)

---

Why GOWA CLI?

• Single binary — Pure Go, no runtime dependencies.
• Agent-native — JSON output, semantic exit codes, structured errors, and gowa context.
• Safety-first — Rate limiter, circuit breaker, audit log, and typing simulation.
• Daemon architecture — Millisecond command latency via Unix socket.

---

Installation

From source (recommended)

go install github.com/murilloimparavel/gowa-cli@latest

Pre-built binaries

Download from GitHub Releases.

---

Commands Summary

Core & Session

Command	Description
gowa pair	Link WhatsApp via QR code
gowa context	State dump for AI agents (highly recommended)
gowa account [add|list|use|remove]	Manage multiple WhatsApp profiles
gowa logout [--purge]	Unlink session and delete data

Daemon

Command	Description
gowa daemon [start|stop|status|logs]	Manage background connection process

Messaging

Command	Description
gowa send text	Send text messages (supports --reply, --dry-run)
gowa send [image|file|voice]	Send media files
gowa send reaction	Add/remove emoji reactions
gowa send edit	Edit previously sent messages
gowa send delete	Revoke sent messages
gowa send forward	Forward messages between chats

Chats & Contacts

Command	Description
gowa chat [list|unread|read|mark-read]	Manage conversations
gowa chat messages JID	Fetch message history
gowa chat search "query"	Global full-text search (FTS5)
gowa chat [archive|pin|mute]	Organize your inbox
gowa contact [list|search]	Manage WhatsApp contacts
gowa alias [set|list|remove]	Named shortcuts for JIDs

Advanced

Command	Description
gowa group [info|list|create|leave|join]	Group management
gowa channel [list|messages|sub|unsub]	Subscribe to newsletters
gowa privacy [list|set|check]	Per-JID read/write access control
gowa media download	Download files from messages
gowa sync [history|status]	Control server synchronization
gowa doctor [--fix]	Diagnose system and connection health

---

Architecture & Safety

GOWA CLI uses a stateless CLI client communicating with a background daemon via Unix Domain Sockets. It embeds whatsmeow for the protocol and SQLite for message persistence.

Safety Layers:

• Atomic Rate Limiting (3/min, 30/hr, 200/day)
• Connection Circuit Breaker
• Typing simulation (Human-like behavior)
• Mandatory --accept-risk flag for all write operations

---

Contributing

See CONTRIBUTING.md.

make build && make test && make lint

---

License

MIT. Created by Murillo Alves.