watui

A minimal WhatsApp TUI, specifically designed to reduce dependency on a browser or desktop application.

Philosophy: Most of the time you do not require past conversation context visible for a reply. And you often have to keep whatsapp (either in web or desktop-app) open anticipating a message from someone, this eats up a lot of RAM of your system (which you were saving for absolutely nothing).

So WA-TUI, just shows you the unread messages with message context persisting only for your active session. Although, you can start a new chat with any contact on demand. It is however a stripped down version of WhatsApp.

What you can do:

Media and document preview (and saving them ofc)
View statuses of your contacts
Read-receipts supported
Load chat history on-demand
Attach files without leaving the terminal emulator
Initiate a message to a WA number
Ghost your nemesis by adding them in your config
Desktop notification

idk, probably there are stuff that you can't do... but i dont really see the need for them, point them out if you disagree. However, if you really feel that you would not want to compromise on these, you should be using the official web or desktop version for such tasks.

I must repeat, WATUI is not a replacement to the official WhatsApp, it's just what you need most of the time.

If you are concerned about security, the db is only accessible in your machine, encrypted with a key and your machine-id (guid). I would rather trust my local machine than a google's server.

Installation

Pre-built binaries are available on the Releases Page.

Linux

Download watui-linux-amd64.tar.gz from the latest release:

tar -xzf watui-linux-amd64.tar.gz
cd watui-linux-amd64

Move the binary into your PATH:

install -m 755 watui ~/.local/bin/watui
# (Ensure ~/.local/bin is in your $PATH)

(Optional) Set up your config:

mkdir -p ~/.config/watui
cp watui.example.yaml ~/.config/watui/config.yaml

Using Nix Flakes (NixOS / any distro with Nix)

# Run directly without installing:
nix run github:Arun0A/watui

# Or start a development shell:
nix develop github:Arun0A/watui

Windows

Download watui-windows-amd64-portable.zip from the latest release.
Extract the zip file anywhere (e.g. C:\Tools\watui or your preferred location).
The folder contains watui.exe and watui.yaml.
Launch watui.exe from PowerShell, Command Prompt, or Windows Terminal:
```
.\watui.exe
```
(Optional) To run watui from any terminal, add the folder containing watui.exe to your Windows Path environment variable.

macOS

[I don't own a macOS machine, reporting any reviews/issues is appreciated]

Download watui-darwin-arm64.tar.gz (Apple Silicon) from the Releases page:
```
tar -xzf watui-darwin-arm64.tar.gz
cd watui-darwin-arm64
```

Move the binary into your PATH:

sudo install -m 755 watui /usr/local/bin/watui
# Or to user local bin:
mkdir -p ~/.local/bin && cp watui ~/.local/bin/

(Optional) Setup your configuration:

mkdir -p ~/.config/watui
cp watui.example.yaml ~/.config/watui/config.yaml

If macOS Gatekeeper flags the binary on first launch, allow it via:
```
xattr -d com.apple.quarantine ~/.local/bin/watui
```

First-Time Setup & Pairing

Open your terminal and launch:
```
watui
```
A QR code will appear in your terminal.
Open WhatsApp on your mobile phone:
- Tap Settings (or ⋮ on Android) ➔ Linked Devices ➔ Link a Device.
Scan the QR code in your terminal.
You're in! Your session credentials are saved in your local encrypted database. Future launches connect immediately.

Keybindings

[Most of them are provided as hint as you use watui.]

Inbox View (Main Screen)

Key	Action
`j` / `k` (or `Ctrl`+`n` / `Ctrl`+`p`)	Navigate unread / pinned conversations
`g` / `Home`	Jump to top of conversation list
`G` / `End`	Jump to bottom of conversation list
`Enter` / `l`	Open selected conversation
`a`	Toggle Archived chats section (press again or `Esc` to return)
`Shift`+`a` / `A`	Archive / Unarchive selected conversation
`Shift`+`m` / `M`	Toggle global mute (1h, 8h, always)
`m`	Toggle local mute in `watui.yaml`
`p`	Toggle local pin in `watui.yaml`
`n`	Start a new chat (search all contacts & groups)
`Ctrl`+`h` / `Ctrl`+`/`	Open all keybinds menu (also `F1`)
`q` / `Ctrl`+`c`	Quit watui

Chat View

Key	Action
`Type text` + `Enter`	Send message (quotes selected message if replying)
`Esc`	Cancel reply / Back to inbox
`Ctrl` + `h` / `Ctrl` + `/`	Open all keybinds menu (also `F1`)
`Alt` + `j` / `k`	Navigate through every message in the chat (message hover mode)
`J` / `K` (while hovering)	Jump to next / previous media message
`Alt` + `m`	Jump to media messages from message box
`r` (while hovering)	Reply to selected message (focuses message box)
`e` (while hovering)	Edit hovered sent message in message box
`i` (while hovering)	View message info (read receipts & delivery details for sent messages)
`y` (while hovering / multi-select)	Copy hovered or selected messages (text only) to clipboard
`l` (while hovering)	Open link(s) in default browser
`p` (while hovering)	Preview selected media or open document prompt
`Space` (while hovering)	For multiple selection of messages
`s` (while hovering / multi-select)	Save hovered media or selected messages to default download dir
`Shift` + `s` / `S` (while hovering / multi-select)	Choose download location via file picker (`yazi`, etc.) and save
`d` (while hovering / multi-select)	Delete hovered or selected messages for you (confirms y/N)
`Shift` + `d` (while hovering / multi-select)	Delete hovered or selected messages for everyone, if possible (confirms y/N)
`Esc` (while hovering)	Clear selection (or return to message box)
`Alt` + `p`	Preview most recent media attachment (or preview highlighted chat in inbox)
`Alt` + `x`	Stop media / audio playback immediately
`Ctrl` + `v` / `Alt` + `v`	Paste image, file, or text from clipboard into message box (`file:///...`)
`Alt` + `f`	Open file picker to attach and send a file
`Ctrl` + `u`	Fetch 5 older messages on demand (when `persist_chat_history` is enabled) / Scroll up
`PgUp` / `PgDn` (or `Ctrl`+`y` / `e`)	Scroll conversation history up / down
`Alt` + `Enter` / `Ctrl`+`j`	Insert newline (multi-line message)

Background Notification Daemon

watui -d                  # Start daemon in background (or: watui daemon start)
watui daemon status       # Check daemon status (or: watui -d status)
watui daemon stop         # Stop the background daemon (or: watui -d stop)
watui daemon restart      # Restart daemon (or: watui -d restart)

When the daemon is running, launching watui attaches via local IPC for an instantaneous startup.
If the daemon is not running, watui automatically runs standalone as normal.
Consumes ~15-20 MB of RAM (50x less than WhatsApp Web or Desktop).
Notification are configurable in the config file.

Headless CLI Message Sending (`--no-tui`)

Send WhatsApp messages directly from the terminal, shell scripts, or CI/CD pipelines without opening the TUI:

# 1. Send plain text message to contact/group/phone JID
watui --no-tui 123456789@s.whatsapp.net "Hello from terminal script!"

# 2. Pipe message from stdin
echo "Disk usage warning: 92%" | watui --no-tui 123456789@s.whatsapp.net -

# 3. Send file attachment or media with optional caption
watui --no-tui 123456789@s.whatsapp.net "file:///path/to/report.pdf Weekly status report"

# 4. JSON output format (for scripts & API integrations)
watui --no-tui -json 123456789@s.whatsapp.net "Status check"

Contact Picker (New Chat)

Key	Action
`Type query`	Real-time fuzzy filter contacts and groups
`Ctrl` + `n` / `p`	Select contact / group
`Enter`	Open chat window
`Esc`	Cancel and return to inbox

Configuration (`watui.yaml`)

watui automatically checks for a config file at:

./watui.yaml (Current working directory)
~/.config/watui/config.yaml (Linux / macOS)
%APPDATA%\watui\config.yaml (Windows)
Or pass explicitly: watui -config /path/to/custom.yaml (5. Media cache directory is the standard cache location of your OS.)

See watui.example.yaml for a full documented template:

# 1. Pinned chats
pin:
  - "91XXXXXX9-15XXXXXX2@g.us" # JID or name supported

# 2. Hidden chats (completely excluded from unread inbox & contacts)
hide:
  - "*@newsletter"         # Hide all WhatsApp Channels
  - "status@broadcast"     # Hide WhatsApp Status updates

# 3. Muted chats (silences notifications only; still shows in unread inbox)
mute:
  - "High Volume Group"

# 4. Media Preview Commands (defaults to OS / MIME default: xdg-open on Linux, open on macOS, default app on Windows)
preview:
  image: "feh -."        # Optional override (e.g. feh, mpv --loop=inf)
  video: "mpv"           # Optional override
  document: "xdg-open"   # General document fallback
  extensions:            
    pdf: "sioyek"
    txt: "nvim"
    log: "less"

# 5. File Picker Command (Alt+F)
# Supported: yazi, ranger, lf, nnn, fzf, zenity, kdialog
file_picker: "yazi"

# 6. Custom Companion Device Name
device_name: "WA-TUI"

# 7. Database Directory or Path (Optional)
# db_dir: "~/.local/share/watui"      # Stores watui.db inside this folder
# db_path: "~/.local/share/watui/watui.db"

# 8. Include / Alternate Config File (Optional)
# config_file: "~/.config/watui/config.yaml"

# 9. Notifications (Banners & Sound Effects)
# Disabled by default. Muted chats never trigger alerts.
notifications:
  enabled: true          # Master toggle: set to true to enable alerts
  banner: true            # Desktop notification banner (notify-send on Linux, toast on Windows, macOS)
  sound: true             # Audio chime on incoming message
  # sound_path: ""          # Custom audio file path (defaults to assets/default.mp3)
  # only_on_mention: true   # Group chats: notify only when mentioned/tagged (@you). Works irrespective of archive status (default: false)

# 10. Chat Reactions Display (Optional)
# Set to true to completely hide reactions in chat view (false by default)
# disable_reactions: false

# 11. Clipboard Paste Support (Optional)
# Set to false to disable pasting images/files/text from clipboard (true by default)
# clipboard_paste: true

# 12. Media Cache Expiration & Cleanup (Optional)
# expire_media: 72       # Cache lifetime in hours (default: 72 hours / 3 days; 0 to disable expiration)
# clear_on_exit: false   # Set to true to clear all cached media on TUI exit (default: false)

# 13. Emoji & Reaction Display Mode (Optional)
# Controls how emojis/reactions are displayed in the terminal:
#   "icon" (default) - Native Unicode emoji glyphs
#   "text"           - Unicode CLDR short name (e.g. :thumbs up:, :grinning face:), ideal for Linux TTY/consoles
# display_emoji: icon

Theme Customization (`theme.yaml`)

By default, watui uses a built-in Catppuccin Mocha color palette without requiring any extra files.

To customize colors, create a theme.yaml in your configuration directory (~/.config/watui/theme.yaml) or next to the watui executable. You can override any key, or just a few. Omitted keys automatically fall back to their default values.

See theme.example.yaml for all available color options and documentation.

Building from Source

Prerequisites

Go 1.26+ (or Go 1.24+)
GCC / Clang (CGO is required by the SQLCipher SQLite engine)

# 1. Clone repository
git clone https://github.com/Arun0A/watui.git
cd watui

# 2. Build executable
go build -o watui ./cmd/watui

# 3. Run
./watui

Questions?

If you have any questions, go to the discussion panel.

If find any major issues, create an issue.

If you want to contribute, create an issue, and then create a PR (resolving the issue).

If you want to thank me... your welcome :) (consider giving me a star?)

License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
cmd/watui		cmd/watui
internal		internal
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
demo.gif		demo.gif
flake.lock		flake.lock
flake.nix		flake.nix
go.mod		go.mod
go.sum		go.sum
theme.example.yaml		theme.example.yaml
watui.example.yaml		watui.example.yaml

Navigation Menu

Repository navigation

About

Repository files navigation

watui

What you can do:

Installation

Linux

Using Nix Flakes (NixOS / any distro with Nix)

Windows

macOS

First-Time Setup & Pairing

Keybindings

Inbox View (Main Screen)

Chat View

Background Notification Daemon

Headless CLI Message Sending (`--no-tui`)

Contact Picker (New Chat)

Configuration (`watui.yaml`)

Theme Customization (`theme.yaml`)

Building from Source

Prerequisites

Questions?

License

About

Releases

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

watui

What you can do:

Installation

Linux

Using Nix Flakes (NixOS / any distro with Nix)

Windows

macOS

First-Time Setup & Pairing

Keybindings

Inbox View (Main Screen)

Chat View

Background Notification Daemon

Headless CLI Message Sending (--no-tui)

Contact Picker (New Chat)

Configuration (watui.yaml)

Theme Customization (theme.yaml)

Building from Source

Prerequisites

Questions?

License

About

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages

Headless CLI Message Sending (`--no-tui`)

Configuration (`watui.yaml`)

Theme Customization (`theme.yaml`)