https://github.com/muhammedaksam/waha-tui
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.
https://github.com/muhammedaksam/waha-tui
chat cli messaging opentui terminal tui waha whatsapp
Last synced: 6 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/muhammedaksam/waha-tui
- Owner: muhammedaksam
- License: mit
- Created: 2025-12-17T10:56:46.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-12-31T14:14:28.000Z (7 months ago)
- Last Synced: 2026-01-04T08:48:59.773Z (7 months ago)
- Topics: chat, cli, messaging, opentui, terminal, tui, waha, whatsapp
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@muhammedaksam/waha-tui
- Size: 2.61 MB
- Stars: 225
- Watchers: 0
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# WAHA TUI
> **WhatsApp in your terminal.**
[](https://www.npmjs.com/package/@muhammedaksam/waha-tui)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://bun.sh/)
[](https://github.com/muhammedaksam/waha-tui/actions)
> ⚠️ **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)](https://github.com/devlikeapro/waha). Manage your WhatsApp sessions, chats, and messages directly from your terminal with an intuitive TUI powered by [OpenTUI](https://opentui.com).
## 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)
```bash
bunx @muhammedaksam/waha-tui
```
### Or install globally
```bash
bun add -g @muhammedaksam/waha-tui
waha-tui
```
### Or clone and run locally
```bash
git clone https://github.com/muhammedaksam/waha-tui.git
cd waha-tui
bun install
bun dev
```
## Prerequisites
- [Bun](https://bun.sh) >= 1.0
- A running [WAHA server](https://github.com/devlikeapro/waha)
### 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:
```json
{
"name": "default",
"config": {
"webjs": {
"tagsEventsOn": true
}
}
}
```
> **Note**: This setting is required for real-time typing indicators to work. See [WAHA documentation](https://waha.devlike.pro/docs/how-to/sessions/#webjs) 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)
```env
# 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)
```json
{
"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:
```env
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:
```bash
# 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](DEVELOPMENT.md) for development setup, commands, and project structure.
## Technologies
- **Runtime**: [Bun](https://bun.sh)
- **UI Framework**: [OpenTUI](https://opentui.com)
- **WAHA SDK**: [@muhammedaksam/waha-node](https://www.npmjs.com/package/@muhammedaksam/waha-node)
- **TypeScript**: Type-safe development
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
## Security
See [SECURITY.md](SECURITY.md) for security policy and reporting vulnerabilities.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Related Projects
- [WAHA HTTP API](https://github.com/devlikeapro/waha) - WhatsApp HTTP API
- [WAHA Node SDK](https://github.com/muhammedaksam/waha-node) - TypeScript SDK for WAHA
- [OpenTUI](https://opentui.com) - Terminal UI framework used by waha-tui