whatscli: The Terminal WhatsApp Every Developer Needs

Tired of context-switching between your terminal and messaging apps? Modern developers live in their terminals, yet communication tools force them into GUI interfaces that break workflow momentum. whatscli shatters this barrier by bringing WhatsApp directly to your command line. This powerful Go-based application transforms your terminal into a full-featured messaging hub without sacrificing the keyboard-driven efficiency you crave.

In this comprehensive guide, we'll explore how whatscli revolutionizes terminal-based communication. You'll discover its robust feature set, master the installation process across multiple platforms, and learn advanced techniques for seamless integration into your development workflow. We'll extract real code examples from the repository, compare it against alternatives, and answer critical questions about security and limitations. Whether you're managing servers remotely or simply prefer terminal aesthetics, this tool deserves your attention.

What is whatscli?

whatscli is a sophisticated command-line interface for WhatsApp that connects directly through the Web App API without requiring a browser. Built with Go and powered by the go-whatsapp library, it leverages tview for its terminal user interface. This architectural choice delivers a native, responsive experience that feels remarkably fluid for a console application.

The project emerged from developer Normen's first foray into Go programming, yet demonstrates remarkable maturity in its design. The application runs as a standalone binary across Windows, macOS, Linux, and Raspberry Pi, making it universally accessible to the developer community. Unlike web-based solutions, whatscli operates entirely within your terminal emulator, maintaining the minimalist aesthetic that terminal purists demand.

Why it's trending now: As remote work becomes permanent and developers seek workflow optimization, terminal-native tools have surged in popularity. whatscli taps into this movement by eliminating the friction of switching between coding environments and communication platforms. The recent visibility boost comes from its unique position as one of the few actively maintained CLI WhatsApp clients, despite Facebook's backend changes that have challenged similar projects.

However, users must understand the caveats. The README explicitly warns that it currently crashes for many countries/accounts due to backend server changes (see issues #72 and #51). Facebook's continuous API modifications mean this tool requires ongoing maintenance. There's no auto-reconnect functionality, no message automation, and it only shows existing chats—no new chat creation. These limitations are crucial for setting realistic expectations.

Key Features That Transform Your Terminal

whatscli packs an impressive array of capabilities into its lightweight binary. Let's dissect each feature with technical depth:

Full-Duplex Messaging: The application maintains a persistent WebSocket connection through go-whatsapp, enabling real-time bidirectional communication. Messages flow through Go channels, ensuring thread-safe operations between the UI routine and network handler. This architecture prevents race conditions while delivering sub-second message delivery.

QR Code Authentication: The setup process leverages WhatsApp Web's QR code mechanism. The terminal renders the QR code using ASCII art or block characters, which you scan with your phone's WhatsApp. The session manager stores authentication tokens locally, enabling automatic login on subsequent launches. This eliminates repetitive authentication while maintaining security.

Attachment Management: Unlike simplistic CLI tools, whatscli handles images, videos, audio, and documents. The /sendimage command supports direct file paths without quote wrapping—even for paths containing spaces. Received attachments can be downloaded and opened through external applications, with the system respecting your OS's default file associations.

Group Management: Basic group operations are built-in. You can add or remove participants using /add and /remove commands, which require user IDs. The clipboard integration (Ctrl-c and Ctrl-v) simplifies this process by letting you copy IDs directly from chats or messages.

Desktop Notifications: Powered by the gen2brain/beeep library, whatscli can trigger native OS notifications or terminal bells. This is configurable through whatscli.config, allowing you to choose between subtle terminal alerts or prominent desktop popups.

Cross-Platform Binaries: The release pipeline generates binaries for multiple architectures. The Raspberry Pi support is particularly valuable for IoT developers wanting to build messaging-enabled devices. The macOS Homebrew tap and Arch Linux AUR packages demonstrate community-driven distribution excellence.

Color Customization: The tview foundation enables extensive theming. Every UI element's color can be modified in the configuration file, letting you match your terminal's color scheme or create high-contrast layouts for accessibility.

Message Selection Mode: Pressing Ctrl-w activates a vim-like selection interface. Navigate through messages and press o to open attachments. This modal approach keeps the UI clean while providing powerful interaction capabilities.

Real-World Use Cases Where whatscli Shines

1. Remote Server Administration Imagine monitoring production logs on a remote VPS when a critical alert arrives. Instead of reaching for your phone or switching to a browser, whatscli displays the message in a split pane. You can acknowledge the alert, coordinate with your team, and share log snippets without leaving SSH. The lightweight nature means it won't compete for resources with your monitoring tools.

2. Development Workflow Integration DevOps teams can integrate whatscli into their tmux or screen workflows. Keep it running in a dedicated pane while coding, testing, and deploying. When a colleague shares API credentials or a bug report, copy them directly with Ctrl-c and paste into your editor. The terminal-native operation eliminates the clipboard formatting issues that plague GUI apps.

3. Privacy-Focused Communication For security-conscious developers, whatscli reduces the digital footprint. No browser extensions, no electron apps with telemetry, just a transparent Go binary. You can run it in a sandboxed environment, audit the source code, and control exactly what data persists on disk. The configuration file location is explicitly shown via /help, giving you full control.

4. Low-Resource Environments On aging hardware or minimal VMs, whatscli consumes negligible resources compared to browser-based WhatsApp Web. The Raspberry Pi binary makes it perfect for IoT projects requiring messaging capabilities. A developer built a smart mirror that displays WhatsApp messages using whatscli piped to a framebuffer display.

Step-by-Step Installation & Setup Guide

Method 1: Package Managers (Recommended)

macOS with Homebrew:

# Add the custom tap and install
brew install normen/tap/whatscli

# Verify installation
whatscli --version

Arch Linux (AUR):

# Using yay
yay -S whatscli

# Or manually clone and build
git clone https://aur.archlinux.org/packages/whatscli/
cd whatscli
makepkg -si

Method 2: Precompiled Binaries

1. Visit the GitHub releases page: https://github.com/normen/whatscli/releases
2. Download the appropriate binary for your OS/architecture
3. Extract and move to your PATH:

# Example for Linux x86_64
tar -xzf whatscli_0.6.5_linux_amd64.tar.gz
sudo mv whatscli /usr/local/bin/
sudo chmod +x /usr/local/bin/whatscli

Method 3: Build from Source

# Clone the repository
git clone https://github.com/normen/whatscli.git
cd whatscli

# Build using Go (requires Go 1.16+)
go build -o whatscli main.go

# Or use the Makefile
make build

# Install to system
sudo make install

Initial Setup

Launch whatscli for the first time:

whatscli

QR Code Scanning Tips:

• Terminal too small? Maximize the window or reduce font size (Ctrl+- in most terminals)
• Can't see the whole code? The QR code adapts to terminal dimensions. Try whatscli > /dev/null to hide logs
• Scanning fails? Restart the app. The QR code expires after 30 seconds

Post-Authentication: Once scanned, chats populate automatically. The session persists in ~/.config/whatscli/. To logout completely, type /logout in the app.

REAL Code Examples from the Repository

Example 1: Homebrew Installation Command

The README provides this exact command for macOS users:

brew install normen/tap/whatscli

Explanation: This command adds Normen's custom Homebrew tap, which hosts the whatscli formula. Taps are third-party repositories that expand Homebrew's package offerings. The installation automatically handles dependencies, binary placement, and PATH configuration.

Example 2: Sending Image Attachments

The core file-sending functionality demonstrates the parser's intelligence:

/sendimage /path/to/file.jpg

Technical Breakdown: The command parser automatically handles spaces in paths without requiring quotes or escaped characters. This is a deliberate design choice mentioned in the README. The session manager validates the file exists, checks MIME type, and streams it through the go-whatsapp library's media uploader. The WebSocket connection sends it as a binary payload with proper encryption.

Example 3: Configuration File Settings

The configuration system uses INI format. Here's a snippet from the documented options:

[notifications]
enable_notifications = true
use_terminal_bell = false

[display]
show_command = jp2a --width=80 --height=40

Explanation: The gopkg.in/ini.v1 library parses this into a singleton Config struct. The show_command parameter demonstrates external program integration—whatscli pipes image data through this command, capturing UTF-8 output for terminal display. The notification settings toggle between desktop alerts and audible bells.

Example 4: Key Binding Configuration

While not a direct code snippet, the README references this usage pattern:

Ctrl-w  # Enter message selection mode
Ctrl-c  # Copy user ID to clipboard
Ctrl-v  # Paste clipboard to input field

Implementation Detail: These bindings are managed by the tslocum/cbind library, which provides customizable keyboard shortcuts in tview applications. The keymap is loaded from whatscli.config, allowing users to override defaults. The clipboard integration uses OS-native APIs through the atotto/clipboard library.

Example 5: Build Commands from Source

For developers wanting to contribute:

go build  # Standard Go build
make      # Uses included Makefile

Architecture Insight: The Makefile likely includes flags for cross-compilation, enabling the multi-platform releases. The main.go contains the tview app running on the main goroutine, while messages/session_manager.go runs the WebSocket connection in a separate goroutine. This separation ensures UI responsiveness even during network latency.

Advanced Usage & Best Practices

Optimize Image Display: For true-color terminal support, install PIXterm:

go install github.com/eliukblau/pixterm@latest

Then update whatscli.config:

[display]
show_command = pixterm -w 80 -h 40

Tmux Integration: Run whatscli in a tmux pane with custom notifications:

# In your .tmux.conf
set-option -g monitor-activity on
set-option -g visual-activity off

Security Hardening: Since Facebook doesn't endorse these clients, protect your session:

chmod 600 ~/.config/whatscli/session.gob

Backup Strategy: Export your configuration:

cp ~/.config/whatscli/whatscli.config ~/dotfiles/

Performance Tuning: For slow connections, reduce the message history limit in config to prevent initial load lag.

Comparison: whatscli vs Alternatives

Why choose whatscli? It's the simplest terminal solution for single-account usage. While Nchat offers more features, whatscli's Go-based architecture delivers better performance and easier compilation. The tview UI feels more responsive than Nchat's ncurses implementation.

Frequently Asked Questions

Q: Is whatscli safe to use with my primary WhatsApp account? A: It uses the same Web API as WhatsApp Web, so security is equivalent. However, Facebook may temporarily flag unusual connections. Always use the latest version and avoid spamming to reduce ban risk.

Q: Why does it crash immediately after scanning the QR code? A: This is the known regional backend issue (#72, #51). Some countries' WhatsApp servers changed their protocol. Try the latest release or build from source. If problems persist, your account may be affected—consider using a test account.

Q: Can I send messages through shell scripts or cron jobs? A: No, and this is intentional. The README explicitly states "no automation of messages, no sending of messages through shell commands." This design prevents spam abuse and aligns with WhatsApp's terms. For automation, consider the Matrix protocol or Telegram's bot API.

Q: How do I run multiple WhatsApp accounts simultaneously? A: whatscli doesn't support multi-account natively. Workaround: Run separate instances with different config directories:

whatscli --config-dir ~/.config/whatscli-work/

Q: What's the best terminal for displaying images? A: Kitty and iTerm2 support true-color and inline images. For best results with jp2a, ensure your terminal is at least 80x40 characters. The pixterm tool works better for complex images.

Q: Can I export chat history? A: Not directly through commands. However, the message database is stored in ~/.config/whatscli/messages.db (SQLite format). Use the sqlite3 command-line tool to export:

sqlite3 ~/.config/whatscli/messages.db "SELECT * FROM messages;" > backup.csv

Q: Will Facebook ban me for using this? A: While WhatsApp's terms prohibit unofficial clients, bans are rare for personal use. The risk increases with bulk messaging or automated behavior. Use responsibly and maintain low message volumes.

Conclusion

whatscli represents a bold step toward unified developer workflows, merging communication and coding environments into a single keyboard-driven interface. Its Go-powered architecture delivers impressive performance, while the tview foundation provides a surprisingly intuitive terminal UI. Despite regional stability issues and Facebook's API volatility, it remains the most elegant CLI WhatsApp solution available.

The project's transparency about limitations builds trust—there are no false promises about automation or perfect reliability. For developers in supported regions, it eliminates context-switching friction and integrates seamlessly into tmux/screen workflows. The attachment handling and group management features exceed expectations for a terminal tool.

Ready to revolutionize your terminal workflow? Head to the official repository at https://github.com/normen/whatscli—download the latest release, scan that QR code, and experience messaging without leaving your command line. Star the repository to support ongoing development and receive updates about crucial backend fixes. Your terminal deserves this upgrade.