WhatsApp CLI 📱
WhatsApp CLI cross-platform tool with browser automation, session persistence, real-time group monitoring, and an interactive terminal interface.
A powerful Python-based CLI tool for automating WhatsApp Web interactions using Playwright. This tool provides both a standalone interactive terminal and an importable Python module for integration with larger projects.
✨ Features
- 🚀 Interactive Terminal: Beautiful CLI interface with command autocomplete
- 📱 WhatsApp Web Automation: Full browser automation via Playwright
- 🔐 Session Persistence: Save authentication to avoid repeated QR scanning
- 📋 Group Management: List, monitor, and send messages to groups
- 👂 Real-time Listening: Monitor group messages in real-time
- 🎨 Rich Output: Colorful, formatted terminal output
- 🔧 Configurable: Environment-based configuration with interactive prompts
- 📦 Importable Module: Use as a library in your Python projects
- 🌐 Cross-platform: Works on Linux, macOS, and Windows
📋 Requirements
- Python ≥ 3.10
- Poetry (for dependency management)
- Chromium browser (installed automatically by Playwright)
⚡ Quick Start (No pre-installation required)
Step 1: Clone the repository
git clone https://github.com/alexcolls/whatsapp-cli.git
cd whatsapp-cli
Step 2: Run the installer
./run.sh
That's it! The script will:
- Detect if WhatsApp CLI is installed
- Launch the interactive installer if needed
- Let you choose between System, Development, or Both installation
- Handle all dependencies automatically
- Run the CLI when ready
Installation Modes
🌍 System Installation (Recommended)
- Installs globally as
whatsapp-cli command
- Available system-wide, run from anywhere
- Easier to use for daily tasks
./install.sh --system
# Then use: whatsapp-cli
🛠️ Development Installation
- Installs locally with Poetry
- Perfect for testing and development
- Keeps everything isolated
./install.sh --dev
# Then use: ./run.sh
🔥 Both Modes (System + Development)
- Installs both system-wide command AND local development
- Use
whatsapp-cli anywhere for daily use
- Use
./run.sh for development and testing
- Best of both worlds!
./install.sh --both
# Then use: whatsapp-cli (system) OR ./run.sh (dev)
🔍 Dry-run Mode
./install.sh --dry-run # Test without installing
📖 More details in QUICKSTART.md
🚀 Installation Options
Automated Installation (Recommended)
Use the installation script for guided setup:
./install.sh # Interactive mode (choose 1/2/3)
./install.sh --system # System-wide installation only
./install.sh --dev # Development installation only
./install.sh --both # Both system + development (recommended)
Manual Installation
For advanced users or custom setups:
1. Clone the repository
git clone https://github.com/alexcolls/whatsapp-cli.git
cd whatsapp-cli
2. Install dependencies with Poetry
Make sure to have python 3.10+ installed. If not, install it: https://www.python.org/downloads/.
Make sure you have poetry installed. If not, install it: https://python-poetry.org/docs/#installation.
poetry install
3. (Optional) Install Playwright browsers
If previous step failed for some reason, then run:
poetry run playwright install chromium
Usually this is handled automatically, but run the above if the CLI asks you to install browsers or you encounter browser-related errors.
4. Configure environment (optional)
cp .env.sample .env
# Edit .env with your preferred settings
🎯 Usage
Standalone CLI
Run the interactive WhatsApp CLI:
poetry run whatsapp
You'll be greeted with an interactive shell:
╭─────────────────────────────────────────────╮
│ │
│ WhatsApp CLI v0.1.0 │
│ │
│ Easy-to-use WhatsApp interface for │
│ your terminal │
│ Type 'help' for available commands │
│ │
╰─────────────────────────────────────────────╯
whatsapp>
Available Commands
| Command | Description | Example |
|---|
start | Connect to WhatsApp Web (scan QR if needed) | start |
list-groups | List all available groups/chats | list-groups |
listen <group> | Listen to messages from a group | listen 1 or listen "Family Group" |
send <group> <msg> | Send a message to a group | send 1 "Hello everyone!" |
help | Show help message | help |
exit | Exit the CLI | exit |
Example Session
whatsapp> start
🚀 Starting WhatsApp bot...
📱 Please scan the QR code with your phone to authenticate
Waiting for authentication...
✓ Authentication successful!
✓ Session saved
✓ WhatsApp bot connected and ready!
whatsapp> list-groups
📋 Fetching groups...
WhatsApp Groups/Chats
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ # ┃ Name ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ Family Group │
│ 2 │ Work Team │
│ 3 │ Friends │
└──────┴─────────────────────┘
Total: 3 groups/chats
whatsapp> listen 2
✓ Opened group: Work Team
👂 Listening to 'Work Team'... (Press Ctrl+C to stop)
[10:45] John: Hey everyone
[10:46] Sarah: Hi!
^C
Stopped listening
whatsapp> send 2 "Thanks for the update!"
✓ Opened group: Work Team
✓ Message sent to Work Team
whatsapp> exit
👋 Goodbye!
As a Python Module
Import and use WhatsAppBot in your Python projects:
from pathlib import Path
from whatsappcli import WhatsAppBot
# Initialize bot
bot = WhatsAppBot(
session_path=Path.home() / ".whatsapp-cli" / "session",
headless=False
)
# Start and connect
bot.start()
# List groups
groups = bot.get_groups()
for group in groups:
print(f"{group['id']}: {group['name']}")
# Send a message
bot.send_message("Family Group", "Hello from Python!")
# Listen to messages with callback
def handle_message(msg):
print(f"New message from {msg['sender']}: {msg['text']}")
bot.listen_to_group("Work Team", callback=handle_message)
# Stop bot
bot.stop()
⚙️ Configuration
Configuration is managed via a .env file. Copy .env.sample to .env and customize:
# Session Management
WHATSAPP_SESSION_PATH=/home/quantium/.whatsapp-cli/session
# Run browser in headless mode (true/false)
WHATSAPP_HEADLESS=false
# Logging Configuration
LOG_LEVEL=INFO
# Optional: Path to log file (leave empty for console only)
LOG_FILE=
# Optional: Comma-separated list of default groups
DEFAULT_GROUPS=
If values are missing from .env, the CLI will prompt you interactively.
🏗️ Project Structure
whatsapp-cli/
├── src/
│ └── whatsappcli/
│ ├── __init__.py # Package initialization
│ ├── __main__.py # CLI entry point
│ ├── bot.py # WhatsAppBot class
│ ├── commands.py # CLI command handlers
│ ├── session.py # Session management
│ └── utils.py # Utility functions
├── pyproject.toml # Poetry configuration
├── .env.sample # Environment template
├── .gitignore
├── CHANGELOG.md
├── LICENSE
└── README.md
🔧 Development
Running in Development Mode
# Install with dev dependencies
poetry install
# Run CLI
poetry run whatsapp
# Run with Python directly
poetry run python -m whatsappcli
Testing the Module Import
poetry run python -c "from whatsappcli import WhatsAppBot; print('Import successful!')"
📝 Notes
- First Run: On first run, you'll need to scan a QR code with your phone to authenticate
- Session Persistence: After initial authentication, sessions are saved locally
- Browser Mode: Use
WHATSAPP_HEADLESS=false to see the browser window (useful for debugging)
- WhatsApp Web: This tool uses WhatsApp Web, so your phone needs to be online
- Rate Limits: Be mindful of WhatsApp's rate limits when sending messages
🤝 Contributing
We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions, your help is appreciated.
How to Contribute
- Report Issues - Found a bug? Open an issue
- Suggest Features - Have an idea? Start a discussion
- Submit Pull Requests - Want to contribute code? See our Contributing Guide
Quick Start for Contributors
# Fork and clone the repository
git clone https://github.com/YOUR-USERNAME/whatsapp-cli.git
cd whatsapp-cli
# Install development dependencies
./install.sh --dev
# Make your changes and test
./run.sh
# Submit a pull request
For detailed guidelines, coding standards, and best practices, please read our CONTRIBUTING.md.
📄 License
See the LICENSE file for details.
🔗 Integration
This module is designed to be easily imported into larger Python projects. Simply install it as a dependency and import the WhatsAppBot class:
from whatsappcli import WhatsAppBot
Perfect for social media management tools, automation scripts, or multi-platform messaging systems!
📊 Project Info
⚠️ Disclaimer
This tool is for educational and personal use only. Make sure to comply with WhatsApp's Terms of Service. The authors are not responsible for any misuse of this tool.
Important Notes:
- This tool uses WhatsApp Web (not the official API)
- Your phone must be online and connected to the internet
- Automated/bulk messaging may violate WhatsApp's terms
- Use responsibly and respect privacy
🙏 Acknowledgments
Made with ❤️ using Python, Playwright, and Rich