WAHA TUI

May 5, 2026 · View on GitHub

WhatsApp in your terminal.

⚠️ Beta - This project is under active development. Some features may be incomplete or change between releases.

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.

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, (edited) indicators, and auto-history loading
📊 Interactive Polls - View and vote in polls with real-time result progress bars (█░)
🔗 Link Previews - Rich metadata rendering for URLs (title, description, domain) directly in the chat
🔍 Search & Filters - Filter chats by all, unread, favorites, groups, or labeled with instant global and in-chat search
📋 Context Menus - Right-click style menus for chats (archive, delete, mark unread, pin, mute) and messages (star, pin, react, forward, delete)
⚙️ Settings - Configurable notification preferences, enter-to-send, and background sync
🔔 Desktop Notifications - Native OS notifications for messages and calls with per-category controls
⏱️ Disappearing Messages - Visibility indicators for chats with disappearing mode enabled
🔄 Real-Time Updates - WebSocket-powered live updates for messages, reactions, polls, labels, and typing indicators
🆕 Update Checker - Automatic notification when a new version is available

Screenshots

Configuration Connect

QR Code Login

Main Screen Conversation View

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 & Settings)

{
  "version": "1.6.1",
  "createdAt": "2024-12-19T00:00:00.000Z",
  "updatedAt": "2024-12-19T00:00:00.000Z",
  "settings": {
    "enterIsSend": true,
    "messageNotifications": {
      "showNotifications": true,
      "showReactionNotifications": false,
      "playSound": true
    },
    "groupNotifications": {
      "showNotifications": true,
      "showReactionNotifications": false,
      "playSound": true
    },
    "statusNotifications": {
      "showNotifications": false,
      "showReactionNotifications": false,
      "playSound": false
    },
    "showPreviews": true,
    "backgroundSync": true
  }
}

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

Key	Action
`1`	Go to Sessions view
`2`	Go to Chats view
`Ctrl+C`	Exit immediately

QR / Phone Pairing

Key	Action
`p`	Switch to phone pairing mode
`q`	Switch to QR mode / Go back
`0-9`	Enter phone number digits
`Backspace`	Delete last digit
`Enter`	Submit phone number
`Esc`	Cancel phone pairing

Sessions

Key	Action
`↑/↓`	Navigate session list
`Enter`	Select session
`Home/End`	Jump to first / last session
`n`	Create new session
`r`	Refresh sessions
`q`	Logout & delete selected session

⚠️ The q key in Sessions view performs a destructive action: it logs out and deletes the current session.

Chats

Key	Action
`↑/↓`	Navigate chat list
`Enter`	Open selected chat
`Home/End`	Jump to first / last chat
`PageUp/Left`	Page up (12 items)
`PageDown/Right`	Page down (12 items)
`Tab/Shift+Tab`	Cycle filters (all/unread/favorites/groups/labeled)
`/` or `Ctrl+F`	Focus search input
`n`	Start new chat
`c`	Open chat context menu
`s`	Open settings
`r`	Refresh chats
`Ctrl+A`	Toggle archived chats view
`Esc`	Clear search / Exit archived / Go back

Conversation

Key	Action
`i`	Enter message input mode
`↑/↓`	Scroll messages
`PageUp/Left`	Scroll up (large jump)
`PageDown/Right`	Scroll down (large jump)
`o`	Open/download last media message
`p`	Create poll
`a`	Attach media
`e`	React with emoji to last message
`m`	Open message context menu
`/` or `Ctrl+F`	Open in-chat search
`Esc`	Exit input mode / Clear search
`Enter`	Next search result (when searching)
`Shift+Enter`	Prev search result (when searching)

Settings

Key	Action
`↑/↓` or `j/k`	Navigate menu items
`Enter/Space`	Toggle setting / Open sub-menu
`Esc`	Go back

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

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