wptui

A keyboard-driven WhatsApp client for the terminal.

wptui pairs a Rust Ratatui interface with the Go whatsmeow library, giving you a fast, Vim-flavored chat experience without leaving your terminal.

Demo

demo.mp4

Warning

This project is under active development. Features and behavior may change between versions.

Features

• Link a WhatsApp account with a QR code or a phone pairing code
• Browse and search chats from the terminal
• Send, reply to, edit, delete, copy, and react to messages
• Inspect reactions and quoted messages
• Paste text, images, and files from the clipboard
• Send attachments with captions
• Download and preview media, or open it in an external player
• Display contact avatars and desktop notifications
• Contextual, Vim-inspired keybindings
• Andiveli welcome mark in the chat panel before any conversation is opened

The Chats list has All, Unread, Groups, and Archived views. All, Unread, and Groups exclude archived chats; Archived shows only archived chats. Filter badges count chats with unread messages (each chat once), not individual messages. All, Unread, and Groups count unarchived chats; Archived counts archived chats. Zero counts are hidden. Archive status comes from the linked device's WhatsApp settings. Search narrows the selected view. Switching views does not change messages or read status; a community row contains only groups in that view. Archive changes received from WhatsApp refresh the current view without switching filters. A yellow @ and yellow Archived label signal an unread mention or reply to your message in an archived group; ordinary archived chats and other group messages do not trigger it. Reading that group clears the alert.

Data

Your WhatsApp data — database, media, and session — lives in ~/.local/share/wptui/ on your machine. It is not uploaded anywhere; the client only exchanges data with the WhatsApp servers when it links or syncs, like any official client.

Mouse capture is enabled by default during the pointer-support preview. Add mouse=disable to ~/.local/share/wptui/settings.conf and restart to restore terminal-native selection, or use mouse=enable to explicitly enable terminal-wide capture. When capture is on, Shift+drag may allow native text selection depending on your terminal; it cannot be enabled for individual panes. In this preview, the wheel scrolls painted lists. Clicking a section enters its list, clicking a contact opens it, and clicking an ordinary text message selects it and opens its Enter actions. Clicking a painted URL opens that link, while clicking a file's painted media/path opens the image/video viewer or uses the existing downloaded document/audio action. Empty file-row space only selects. Mouse behavior still needs a fresh live-terminal check.

Requirements

Runtime dependencies

The prebuilt binary links against a few system libraries. On a desktop installation most of them are already present; the one you usually need to install explicitly is libchafa, which is used to render images in the terminal.

• Debian / Ubuntu

  sudo apt install libchafa0t64 libglib2.0-0 libwayland-client0
  

• Fedora

  sudo dnf install chafa glib2 wayland
  

• Arch Linux

  sudo pacman -S chafa glib2 wayland
  

• macOS

  brew install chafa
  

  macOS uses the native file dialogs, so no Wayland libraries are needed.

Build requirements

• Linux or macOS
• A recent stable Rust toolchain with Cargo (the repository pins Rust 1.96.1 via rust-toolchain.toml)
• Go with CGO enabled
• A C compiler supported by CGO
• On Linux, the development packages libwayland-dev, libchafa-dev and libglib2.0-dev; on macOS, chafa from Homebrew
• Optional: mpv for opening media externally

Installation

Prebuilt binary

Prebuilt binaries for Linux (x86_64) and macOS (Apple Silicon) are attached to each GitHub release. Install the one for your system with:

curl -sSL https://raw.githubusercontent.com/Andiveli/wptui/main/install.sh | bash

The script downloads the matching binary from the latest release into ~/.local/bin (override with PREFIX, e.g. PREFIX=/opt/wptui ./install.sh). Make sure the runtime libraries listed in Requirements are present first.

Nix (Linux)

The flake declares wp-tui for x86_64-linux and aarch64-linux; CI builds only the x86_64 Linux package. From a checkout, build the package or run it from the development shell:

nix build .#default
./result/bin/wp-tui --version
nix develop --command wp-tui --version

Run nix develop without --command to enter a shell with wp-tui on PATH. When using the repository as a NixOS flake input, select inputs.wptui.packages.x86_64-linux.default on x86_64 Linux (or inputs.wptui.packages.aarch64-linux.default on ARM Linux).

Build from source

git clone https://github.com/Andiveli/wptui.git
cd wptui
cargo install --path .

The Rust build automatically compiles the bundled Go bridge. See Requirements for the build-time libraries.

Usage

Start the client and scan the QR code displayed in the terminal:

wp-tui

Or request a pairing code using an international-format phone number:

wp-tui --phone +1234567890

Check for and install the latest stable release when using a standalone binary:

wp-tui update

When running through Cargo, separate application arguments with --:

cargo run -- --phone +1234567890

Diagnostics

To trace edited/deleted message processing, run with:

WPTUI_MESSAGE_ACTION_DEBUG=1 cargo run

After quitting, a bounded, redacted trace is printed in the normal terminal.

Keybindings

Keybindings are contextual. Press Esc to close the active menu, picker, search, viewer, reply, or editor state.

Global and navigation

Action	Key
Quit	Ctrl+Q
Toggle logs	Ctrl+Shift+L
Toggle section rail	Space, then 1
Toggle chat list	Space, then 2
Focus previous / next pane	h / l or ← / →
Select previous / next item	k / j or ↑ / ↓
Jump to first / last item	g g / G
Move half a page	Ctrl+U / Ctrl+D
Search chats	/
Cycle chat filters (All, Unread, Groups, Archived)	Tab in the Chats list

Messages

Action	Key
Start composing	i
Copy selected text	y
React	r
Share	s
Reply	R
Edit your text message	e
Delete your text message	d
Delete one selected, published own status (text, image, or video)	d in Status navigation
Open downloaded media	x
View selected image or video	v
Open message actions	Enter

Use j/k or the arrow keys inside menus, then press Enter to confirm. Available actions depend on the selected message. In Status, press Enter on your own contact to open the Create status pane in navigation. Select one published update with j/k or ↓/↑, then press d to revoke it; i starts writing and Esc returns to the contact list. Space, a, c still opens Create status directly in authoring mode; Esc there enters navigation. Pending drafts and other contacts' statuses cannot be deleted this way. A failed revoke leaves the item visible; a successful send removes the local row, but does not itself prove removal from every recipient's device.

Composer and media

Context	Action	Key
Composer	Send	Enter
Composer	Paste text, files, or an image	Ctrl+V
Reaction picker	Move / confirm	j/k or Up/Down arrows / Enter
Media viewer	Previous / next	h/l or arrows

Pasted files are queued as attachments. When text is included, it becomes the caption of the first attachment.

Development

Runtime performance diagnostics

The opt-in profiler is disabled unless WPTUI_PERF=1. Build and run the release binary with the exact command WPTUI_PERF=1 target/release/wp-tui, reproduce the CPU spike or interaction, and exit normally. It writes one bounded report to ~/.cache/wptui/perf-report.txt.

To build and test without using local Cargo resources, see cloud-built preview binaries. Push a preview/** branch based on main when you want a downloadable Linux binary without creating a release.

For contributors who prefer local checks, run the Rust test suite:

cargo test -- --test-threads=1

Run the Go test suite:

cd whatsrust/lib
go test ./...

Continuous integration runs format checks, builds, and both test suites on pushes to main and pull requests. For on-demand feature binaries, start a preview/** branch from main; its pushes run preview checks and upload a Linux binary. To build the integrated main on demand, manually dispatch release.yml on main: it uploads artifacts without publishing a release. Tagged releases remain a separate decision.

Disclaimer

wptui is an unofficial, experimental client. It is not affiliated with, endorsed by, or associated with WhatsApp or Meta Platforms, Inc. Unofficial clients operate in a terms-of-service gray area; use at your own risk, as an account restriction is possible.

License

MIT © 2026 andiveli. See LICENSE.

Third-party components are listed in THIRD_PARTY_NOTICES.md.