WAHA TUI

WhatsApp in your terminal.

⚠️ Work In Progress - This project is in early experimental development. Features may be incomplete, unstable, or change without notice.

A beautiful Terminal User Interface for WhatsApp using WAHA (WhatsApp HTTP API). Manage your WhatsApp sessions, chats, and messages directly from your terminal with an intuitive TUI powered by OpenTUI.

01-introduction.mp4

Features

• 📱 Session Management - Create, view, and manage WAHA sessions with QR code or phone number pairing
• 💬 Chat Interface - Browse chats with WhatsApp-style layout and real-time updates
• ✉️ Messaging - Send and receive messages with read receipts
• 🎨 Beautiful UI - WhatsApp Web-inspired interface with colors and icons
• ⚡ Fast & Lightweight - Built with Bun for blazing-fast performance
• 🔒 Secure - All configuration stored locally in $XDG_CONFIG_HOME/waha-tui/
• 🔄 Auto-Refresh - QR codes refresh automatically, status updates in real-time

Screenshots

Quick Start

Run directly with bunx (no installation required)

bunx @muhammedaksam/waha-tui

Or install globally

bun add -g @muhammedaksam/waha-tui
waha-tui

Or clone and run locally

git clone https://github.com/muhammedaksam/waha-tui.git
cd waha-tui
bun install
bun dev

Prerequisites

• Bun >= 1.0
• A running WAHA server

WEBJS Engine Configuration

If you're using the WEBJS engine (default for WAHA CORE), you must enable tagsEventsOn in your session config to receive typing indicators (presence.update) and message ack events:

{
  "name": "default",
  "config": {
    "webjs": {
      "tagsEventsOn": true
    }
  }
}

Note: This setting is required for real-time typing indicators to work. See WAHA documentation for more details.

Configuration

On first run, WAHA TUI will prompt you for configuration with a beautiful setup wizard.

Configuration is stored in $XDG_CONFIG_HOME/waha-tui/ (defaults to ~/.config/waha-tui/) with secrets separated from metadata:

$XDG_CONFIG_HOME/waha-tui/.env (Secrets)

# WAHA TUI Configuration
# Connection settings for WAHA server

WAHA_URL=http://localhost:3000
WAHA_API_KEY=your-api-key-here

$XDG_CONFIG_HOME/waha-tui/config.json (Metadata)

{
  "version": "1.0.0",
  "createdAt": "2024-12-19T00:00:00.000Z",
  "updatedAt": "2024-12-19T00:00:00.000Z"
}

Development: Project .env

For development, you can also create a .env in the project root which takes precedence:

WAHA_URL=http://localhost:3000
WAHA_API_KEY=your-api-key-here

Usage

Keyboard Shortcuts

Key	Action
↑/↓	Navigate lists
Enter	Select item / Open chat / Submit phone number
Esc	Go back / Cancel phone pairing
i	Enter input mode (in conversation)
r	Refresh current view
n	Create new session (in Sessions view)
p	Switch to phone pairing mode (in QR view)
1	Go to Sessions view
2	Go to Chats view
q	Quit / Go back / Switch to QR mode
Ctrl+C	Exit immediately

Debug Logging

Enable debug logging to troubleshoot issues:

# Via environment variable
WAHA_TUI_DEBUG=1 bun dev

# Via command-line flag
bun dev --debug

Debug logs are saved to $XDG_CONFIG_HOME/waha-tui/debug.log with automatic sanitization of sensitive data.

Development

See DEVELOPMENT.md for development setup, commands, and project structure.

Technologies

• Runtime: Bun
• UI Framework: OpenTUI
• WAHA SDK: @muhammedaksam/waha-node
• TypeScript: Type-safe development

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

See SECURITY.md for security policy and reporting vulnerabilities.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• WAHA HTTP API - WhatsApp HTTP API
• WAHA Node SDK - TypeScript SDK for WAHA
• OpenTUI - Terminal UI framework used by waha-tui