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.mp4
Warning
This project is under active development. Features and behavior may change between versions.
- 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
- See who is typing in the open conversation, including multiple people in a group
- Paste text, images, and files from the clipboard
- Send attachments with captions
- Download and preview media, or open it in an external player
- Play animated WebP stickers while visible in terminals with image support (up to four animations at a time, prioritizing visible stickers as you scroll); long animations are sampled to preserve motion and their normalized frame timing within bounded memory, while excess simultaneous or unsupported stickers retain a still preview
- 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. Search in All also finds saved contacts without chat history. To start a chat with an unsaved number, type / in the Chats list, enter + followed by 7–15 digits (country code included), and press Enter. The app checks whether the number is registered on WhatsApp before opening an empty conversation; it never sends a message automatically. All, Unread, and Groups exclude archived chats; Archived shows only archived chats.
Filter badges count unread chats (each chat once), including manually marked chats,
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.
Messages and attachment captions render WhatsApp formatting locally: *bold*,
_italic_, ~strikethrough~, inline backticks, triple-backtick code, quotes,
and lists. wptui also recognizes **bold**, __bold__, ~~strikethrough~~,
# headings, and [label](https://example.com) links. Headings and quotes also
recognize markers after up to three leading ASCII spaces, preserving indentation
in the display projection and original source. Labeled links show only an
underlined label; clicking it opens the original URL. The active composer
fragment reveals the link source for editing. Formatting never fetches content
or opens a link automatically.
Incoming and outgoing chat text display bare HTTP(S) URLs as the complete host
(including subdomains and any port) plus the final nonempty path segment: for example,
https://github.com/Andiveli/wptui becomes github.com · wptui, while
https://example.com/ becomes example.com. Query strings and fragments are
omitted from the label, not the click destination; path segments are not decoded.
Ambiguous or unsupported authorities remain raw. This helps you inspect the host,
but is not phishing detection or a safety guarantee. No site or title is fetched.
Explicit Markdown links retain the author's chosen label rather than a URL label.
The composer, statuses, captions, reply summaries, system text, code, and literal
image syntax keep their existing display.
When WhatsApp supplies native preview metadata for an eligible incoming or outgoing chat link, bare or explicit Markdown, a compact preview below the body shows its title and description literally (not as Markdown). Only an embedded JPEG can supply the thumbnail; no website, external image URL, or thumbnail direct path is fetched. The host/path or chosen Markdown label and exact click destination remain unchanged. The card binds to the original source occurrence: a protected code/image occurrence cannot borrow eligibility from a later matching URL. Missing or invalid metadata keeps the normal link presentation. Optimistic desktop sends may lack metadata; synced phone-sent messages can carry it. wptui does not generate preview metadata. Thumbnail work is automatic only while its entire reserved image area is visible and not covered by a popup; selection and keyboard focus do not trigger loading. Loading or unusable images keep the same reserved geometry and leave the text and original link usable. The preview adds no clickable card action.
Formatting changes only the local display. Sending, editing, copying, and searching still use the original text; other WhatsApp clients display the syntax they support. The composer previews the same formatting while you type. Markers reappear in the fragment containing the cursor, so you can edit them directly; outside that fragment they do not occupy columns. Drawing, wrapping, and arrow-key navigation share the source-to-display mapping, including Unicode and right-to-left text.
Incomplete markers and unsupported Markdown remain literal. Code is displayed without interpreting formatting inside it. Terminal font support determines whether italic and strikethrough styles are visible.
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.
Startup reads chats, contacts, messages, reactions, and native link-preview metadata
as one SQLite snapshot before applying that history to the app. If hydration fails
(for example, an exhausted SQLite lock wait), wp-tui prints
wp-tui: could not hydrate persisted chat history: <error> and exits with status 1
without connecting to WhatsApp or opening the terminal UI. It does not treat a
failed read as empty or partially loaded history, retry it, or extend the existing
SQLite busy timeout. This error alone does not identify which connection holds a lock.
Incoming and outgoing chat text can retain WhatsApp-supplied link-preview metadata in a separate local database table; old messages without metadata load normally. Native metadata is optional and is displayed only for eligible plain or explicit Markdown chat links in either direction: no website, external image URL, or thumbnail direct path is fetched. Titles are limited to 2,048 UTF-8 bytes, descriptions to 8,192 bytes, and embedded thumbnails to 256 KiB; an oversized image is omitted without discarding valid text metadata. Unsafe or mismatched text metadata is ignored without changing the message or its click destination. Editing or deleting a message clears its preview metadata. Receive adjuncts and app-owned preview state are bounded (64 and 256 entries, respectively); valid persisted metadata remains associated with its message.
Preferences live in your OS configuration directory (~/.config/wptui/settings.conf on Linux).
An existing settings.conf in the data directory is copied there on first use if no config
file exists; the legacy file is left untouched. Set composer_direction=rtl or
composer_direction=auto to choose the composer direction.
Press Space → a → t (Actions → Themes) to choose Default, Kanagawa, One Dark, Catppuccin, Tokyo Night, Gruvbox, or Custom. The current selection is highlighted. Move with Up/Down or j/k; Enter saves and applies immediately without restarting, and Esc cancels without changing settings or colors. A save failure is displayed and leaves the current colors unchanged. Selecting Default clears all earlier theme selections; other settings are preserved.
Alternatively, add one line to ~/.config/wptui/settings.conf on Linux (or your OS
configuration directory) and restart:
theme=kanagawa| Setting value | Variant |
|---|---|
kanagawa |
Kanagawa Wave |
one-dark |
One Dark Pro |
catppuccin |
Catppuccin Mocha |
tokyo-night |
Tokyo Night |
gruvbox |
Gruvbox Dark Medium |
Names are case-sensitive; surrounding whitespace is ignored. Omit theme, leave
it empty, or use an unknown name to retain the existing default appearance.
If repeated, the first recognized theme wins, as with other parsed preferences.
Theme loading does not rewrite your settings or change mouse, composer,
notification, or custom preferences.
Named themes paint an explicit dark canvas and selection fill, so contact names, previews, timestamps, unread indicators and attention markers do not depend on your terminal's background or ANSI palette. The same text, secondary, accent, selection, unread, attention and border roles are used across navigation, contacts, communities, Status, News and the conversation/composer chrome. Existing message formatting and media colors are not remapped. Custom palettes are supported through the JSON file below; there is no transparency toggle.
Secondary text and borders use brighter base-palette roles rather than low-contrast editor comments or separators: Kanagawa's status foreground, One Dark's status foreground, Catppuccin's ANSI white, Tokyo Night's bright white, and Gruvbox's ANSI white. Selection uses each variant's opaque list surface (Gruvbox's focus surface) with light text. Unread/attention use the palette's bright green/yellow roles (Catppuccin uses its regular pastel green/yellow). These adaptations keep small terminal text readable; rendered contact regression tests require at least 4.5:1 contrast on the explicit surfaces. Palette provenance is recorded in Third-Party Notices.
To use your own colors:
- Create
theme.jsonbeside your activesettings.conf(~/.config/wptui/theme.jsonon Linux). - Choose Custom using Space → a → t, then Enter to save and apply. Selecting Custom again reads the current JSON file without restarting.
You can also set theme=custom in settings.conf, replacing earlier recognized
theme entries, and restart. Manual settings-file edits require a restart;
JSON edits require a restart or selecting Custom again. There is no file watcher
or in-TUI color editor, and the selector never rewrites theme.json.
For example:
{
"base": "kanagawa",
"colors": {
"text": "#DCD7BA",
"accent": "#aB12Ef",
"surface": "#1F1F28"
}
}The schema is a JSON object with only these optional fields:
| Field | Accepted value | When omitted |
|---|---|---|
base |
One of kanagawa, one-dark, catppuccin, tokyo-night, gruvbox (case-sensitive) |
kanagawa |
colors |
An object mapping the roles below to color strings; {} is allowed |
No overrides |
The ten allowed color roles are text, muted, accent, selection,
selected_text, unread, attention, border, surface, and error.
selection is the selected-row fill; selected_text is its foreground;
surface is the opaque canvas. Unspecified roles inherit the base palette, so
{} is a complete valid theme using Kanagawa unchanged.
Every color must be exactly #RRGGBB, with six hexadecimal digits; upper,
lower, and mixed case are accepted. Short hex, alpha channels, color names,
transparency, and surrounding whitespace inside the string are not accepted.
Contrast is your choice: custom colors are not automatically adjusted or rejected
for low contrast. Custom themes keep the same explicit opaque canvas as named
ones, using the resolved surface color.
Malformed JSON, unknown fields or roles, an invalid base, wrong value types
(including null), or any invalid color reject the whole file. Missing or
unreadable files likewise use the legacy default appearance, not the base palette;
no partial overrides are applied. The first recognized theme setting still wins:
theme=custom remains selected even when its file falls back, rather than trying
later duplicate settings.
The file is read only when custom is selected. Lookup follows the resolved
settings.conf location: after legacy settings migration, the active configuration
directory wins, and a theme.json left in the data directory is not migrated or
used. Startup theme loading only reads files: it does not create, rewrite, or
repair either file or alter other preferences. Applying a selection in the TUI
updates only theme entries in settings.conf, removing duplicates. Paths,
includes, plugins, and executable code are not supported in the schema.
Press Space, then a, then n to toggle all WPTUI desktop notifications and their audio.
The contextual menu shows the current Notifications: On / Notifications: Off state;
changes apply immediately and are saved to the same settings file. No chat selection is needed.
If saving fails, an error is shown and the current state is kept.
Alternatively, to disable them manually, add this to settings.conf:
notifications=disableUse notifications=enable to enable them explicitly. Notifications are enabled by default
when the setting is missing, invalid, or unreadable. Manual file edits are loaded at startup;
restart WPTUI after editing the file (the menu toggle needs no restart). Disabling notifications
does not change message reception, persistence, synchronization, or unread counts. The existing
notification_sound option selects the sound only when notifications are enabled.
Eligible desktop notifications play the bundled assets/sounds/attention.wav by default,
even when the notification server does not support sound hints. To use your OS/theme sound
instead, set notification_sound=system in settings.conf (this requests a system sound hint;
it depends on your notification server). To play your own sound directly, set
notification_sound=/absolute/path/to/alert.ogg (WAV, MP3 and OGG/Vorbis are supported).
Absent or invalid settings use the bundled sound. Direct playback does not request a second
system sound; an unreadable file or missing audio device is logged without suppressing the
desktop notification. Messages timestamped before this app session started still show desktop
notices, but request neither bundled/custom audio nor a system sound hint. Messages from the
startup second onward remain audible, even while synchronization progress is visible. If the
startup clock is unavailable, audio remains enabled for eligible notices. Muted chats, open
chats and explicit sync traffic remain silent.
Mouse capture is enabled by default during the pointer-support preview. Add mouse=disable to
that config file 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.
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 libasound2 - Fedora
sudo dnf install chafa glib2 wayland alsa-lib - Arch Linux
sudo pacman -S chafa glib2 wayland alsa-lib - macOS
macOS uses the native file dialogs, so no Wayland libraries are needed.
brew install chafa
- 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-devandlibglib2.0-dev,libasound2-dev; on macOS,chafafrom Homebrew - Optional:
mpvfor opening media externally
Media previews and external opening require a kernel-confined file open (Linux
openat2 or macOS O_RESOLVE_BENEATH). On older systems without that support,
these operations fail closed; downloads and chat still work. Symlinks whose
resolved targets remain inside the media directory, including absolute links,
remain usable on supported systems. Video thumbnails are generated from
confined input handles into bounded memory: generated frames are not saved as
sidecars and may be regenerated after a restart or cache eviction. FFmpeg must
support seekable fd: input; otherwise an existing contained sidecar remains
the fallback. Audio duration probes also read already-confined file handles,
not media pathnames.
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 | bashThe script downloads the matching binary from the latest release into
~/.local/bin (override with PREFIX, e.g. PREFIX=/opt/wptui ./install.sh).
New release archives include the bundled tone's MIT notice; the installer keeps
it next to the binary as wp-tui-THIRD_PARTY_NOTICES.md.
Make sure the runtime libraries listed in Requirements are
present first.
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 --versionRun 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).
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.
Start the client and scan the QR code displayed in the terminal:
wp-tuiOr request a pairing code using an international-format phone number:
wp-tui --phone +1234567890Check for and install the latest stable release when using a standalone binary:
wp-tui updateThe updater accepts older binary-only archives and newer archives containing the
bundled tone's MIT notices. It keeps wp-tui-THIRD_PARTY_NOTICES.md beside the
updated executable.
The muted blue-gray News wptui section (or News on a narrow rail) bundles
notes for the installed version and reads GitHub's published stable releases,
newest first, including intermediate newer versions.
It does not show main, drafts, or prereleases. The v0.3.0 release has no supplied
notes; the bundled text says so rather than inventing highlights. Maintainers
should update assets/release-notes.md with the installed release's notes before
building and use the same text in the GitHub release description; follow the
release checklist.
History is limited to eight pages of 100 entries, 1 MiB per page and a three-second request timeout. Reaching the page cap explicitly marks history incomplete. A failed request returns cached newer-version notes marked stale with an error; missing or corrupt cache never implies the installation is up to date. Cache replacement is atomic, and cached content is untrusted display data, not authority to install a binary. Terminal control sequences are stripped before display.
History loads asynchronously at startup and r refreshes it (one request at a time).
The dedicated news-history.json file lives in the OS cache directory. Installed
notes remain available offline. Loading, offline/cached, error and incomplete
history are labeled explicitly; a failed fetch never means “up to date”.
Select installed or intermediate release notes with j/k or arrows; use
Ctrl+U/Ctrl+D to scroll long notes. h/l or
left/right arrows move pane focus; Tab advances focus inside News. The mouse
wheel selects releases over the list and scrolls notes over the body.
News also offers an optional highlighted Star Andiveli/wptui invitation when
GitHub CLI (gh) confirms the repository is not starred. Status is checked once
per session on entering News, in the background with an eight-second timeout.
Already-starred, checking, unavailable, unauthenticated and unknown states hide
the invitation; gh is optional and release notes work without it. Only pressing
s in News or clicking Star sends the explicit GitHub star request. While it
is pending, both actions are disabled; success shows inline thanks, and failure
quietly hides the invitation. Press d in News or click Hide to permanently
dismiss it (stored separately in the app data directory, not configuration).
Unreadable or unwritable invitation state suppresses it. These keys do not change
Messages Share/Delete or Status Delete. No browser or notification is opened.
Press u to install the exact displayed newer stable release, including an
intermediate version. The confirmation names that version; Cancel is selected by
default. Use Up/Down to choose, Enter to confirm, or Esc to cancel. Installed-version
notes cannot be installed. The updater re-fetches the exact tag from the trusted
GitHub API; cached notes never authorize installation. Package-manager, platform,
ownership, checksum and archive protections remain enforced. A working status covers
checking/downloading/installing; errors remain visible and requests are single-flight.
After success, choose Restart now / Later (Later is the safe default). Later
keeps the current version and session running; R opens the restart choice again.
Restart is deferred while drafts, attachments, status composition or pending sends
exist: finish or discard them and press R again. Nothing logs you out. Explicit
restart shuts down normally, joins update/history work, restores the terminal and
executes the newly installed binary with the same arguments and environment. If
relaunch fails, the restored terminal shows an error and exits nonzero; session data
is untouched. Ordinary quit also waits for an installation to finish.
wp-tui update retains its existing latest-stable behavior and safety checks.
When running through Cargo, separate application arguments with --:
cargo run -- --phone +1234567890When a number check finishes unsuccessfully, it leaves the search open without opening a conversation or sending a message. Its result notice appears as plain text; local input validation and unrelated notices retain their existing formatting:
| Notice | Meaning / next step |
|---|---|
Number is not on WhatsApp |
WhatsApp reported that the requested number is not registered. |
Number check timed out |
The check exceeded its deadline; retry the search. |
WhatsApp returned no number result |
No result was returned; retry the search. |
WhatsApp returned a mismatched number result |
A registered reply matched the query but had empty or unexpected identities that did not confirm the requested number; no recipient is opened. Retry the search. |
WhatsApp returned only a LID without a phone number |
A registered reply matched the query with a LID and no associated phone number, without confirming the requested number; no recipient is opened. |
WhatsApp returned a different phone number |
A registered reply matched the query and contained a phone-number identity, but neither identity confirmed the requested number exactly or through the narrow Mexico/Argentina equivalences below; no recipient is opened. |
WhatsApp returned a mismatched query result |
Nonempty replies contained no matching query; no recipient is opened. Retry the search. |
Could not check number |
The request failed; retry the search. |
Could not verify number |
The result could not be safely verified; no recipient is opened. |
WhatsApp is not connected |
Reconnect WhatsApp, then retry the search. |
Use + followed by 7-15 digits |
Correct the international number format, then retry. |
A failed, timed-out, empty, or mismatched check does not mean the number is
unregistered. These notices use fixed categories, without including the entered
number, recipient identity, or raw error details; number lookup adds no diagnostic logging.
The LID-only and different-phone-number categories describe response shape only:
they do not prove legitimate number normalization or permit opening another recipient.
Opening a conversation requires a registered response whose query matches the entered
number (with or without its leading +) and whose phone-number identity confirms it.
Exact matches take precedence across both returned identity fields. Otherwise, only
these two country-number equivalences are accepted, in either direction:
- Mexico:
52+ exactly 10 digits ↔521+ the same 10 digits. - Argentina:
54+ exactly 10 digits ↔549+ the same 10 digits.
All other digit differences remain rejected, including different national suffixes,
wrong lengths, and unsupported countries. This is not domestic-number parsing: it
does not strip Argentina's domestic 15 or leading zero, or guess area codes.
For both exact and equivalent matches, only s.whatsapp.net and WhatsApp's legacy
c.us user namespace are allowed, with the same integrator after device metadata
is removed. An accepted equivalent lookup opens the server-confirmed spelling,
not the originally entered spelling, as a non-device s.whatsapp.net PN identity.
A LID alone never authorizes opening a conversation. No extra lookup is made and
no message is sent automatically.
For the matched, registered response that failed the phone-identity comparison,
this preview opens a local-only, read-only window. It shows the requested
number, response Query and IsIn, and the PhoneNumber and JID fields. Each
identity has a quoted string representation plus labeled User, Server,
RawAgent, Device and Integrator components, so formatting and field order
can be inspected without guessing.
Use j/k or up/down arrows to scroll vertically, h/l or left/right arrows
to scroll horizontally, Home to reset the view, and Esc to close and release
its in-memory observation. Other input is captured by the window: Enter does
not open a conversation or send a message. Values are length-bounded and controls
are escaped as visible ASCII rather than interpreted by the terminal.
Actual values are retained only in volatile memory for this display, with redacted Debug output. They are not added to notices, logs, files, the chat store, or the clipboard. No additional lookup is made; inspection never relaxes the recipient confirmation rules above. Do not share the displayed numbers, JIDs, screenshots, or full response text. Report only whether you see a formatting difference or different digits.
If the local snapshot is unavailable or exceeds its limits, the existing six-boolean comparison remains as a fallback, for example:
Lookup comparison PN(d/n/i)=0/1/1 JID(d/n/i)=0/0/1
PN compares the response's associated phone-number field; JID compares its
other identity field. Each triple contains independent booleans (1 yes, 0 no):
d: the field's user digits exactly equal the entered phone-number digits.n: its domain is an allowed phone-number domain (s.whatsapp.netorc.us).i: itsIntegratorequals the requested identity's integrator (zero).
These are comparisons, not field values or proof of a valid recipient. An absent
field can still have i=1 because its default integrator is zero. No number, JID,
raw response, or diagnostic log is emitted or persisted by the boolean fallback.
Only the existing lookup action makes a request; the preview adds no background
queries, sends no message, and does not relax the recipient confirmation rules
above. The comparison remains a rejected lookup and cannot open a conversation. Share only
the comparison line, not the number, screenshot, or recipient identifiers.
This temporary observation is not a fix for the reported new-number failure.
To trace edited/deleted message processing, run with:
WPTUI_MESSAGE_ACTION_DEBUG=1 cargo runAfter quitting, a bounded, redacted trace is printed in the normal terminal.
To diagnose a read/unread mismatch, use a diagnostic-enabled preview, without resetting your account or repairing local state. From the main checkout root:
The parent will provide the diagnostic-enabled binary's source-stamped filename.
Replace SOURCE_STAMP below with that supplied stamp, keeping the old binary.
The target directory must already exist. Each run creates a unique report directory:
trace_dir=$(mktemp -d "$PWD/.worktrees/chat-read-unread/target/read-sync-trace.XXXXXX") &&
printf 'Read-sync report: %s/trace.txt\n' "$trace_dir" &&
WPTUI_READ_SYNC_TRACE="$trace_dir/trace.txt" \
.worktrees/chat-read-unread/target/release/wp-tui-SOURCE_STAMPThe report path is printed before the TUI starts. Preserve existing reports, archives and binaries; do not delete or overwrite them.
- Select the affected chat without opening it, then use
Space,a,m. - Reopen
Space,aon that same chat and note the label and WhatsApp's state. - Close the TUI normally with
Ctrl+Qbefore inspecting the selected report.
The opt-in report is fresh-file-only: if the selected file already exists,
capture is silently disabled and its bytes remain unchanged. A new report stops
after 100 records across the app and bridge callbacks. It contains only stage
enums, booleans, counters, bridge status and a safe error category—no message
content, identifiers (even hashed),
absolute message timestamps, keys, credentials, raw errors or server payloads.
Without WPTUI_READ_SYNC_TRACE, this trace emits no output. Report I/O failure
is nonfatal and can leave a missing or incomplete report; tracing adds no sends
or retries.
Each completed bridge operation adds stage=initial_send, stage=recovery_fetch
or stage=resend, followed by status=<code> category=<safe-category> using the
existing closed outcomes. Omitted operations produce no stage record. The final
stage=bridge status=<code> category=<safe-category> record is retained, so an
initial rejection remains visible even if recovery succeeds or fails differently.
These records are opt-in diagnostic evidence, not a synchronization fix or proof
that WhatsApp applied the change.
Queue acceptance is not delivery confirmation. A bridge status of 0 only means
the existing call returned successfully; resync_after_send means its follow-up
fetch failed and the update may already have applied. missing_key, key_lookup,
cancelled, timeout, unavailable and other do not establish server acceptance
or a root cause. Exported typed errors use closed app-state, IQ, missing-element
and connection/session categories, never raw error text or IQ codes; unknown IQ
codes remain iq_other, and unrecognized errors remain other.
appstate_with_cause only identifies an app-state error with a structurally wrapped
secondary cause; it does not establish a server code, conflict, or specific cause.
Known secondary sentinels use appstate_cause_key_missing,
appstate_cause_content_mac, appstate_cause_index_mac,
appstate_cause_lt_hash, appstate_cause_patch_mac, or
appstate_cause_previous_set_missing. These identify error classes, not
key/MAC values or a confirmed fix. Unknown secondary errors remain
appstate_with_cause.
Concurrent bridge results may appear between UI snapshots; there are deliberately
no identifying correlation fields. Tracing alone does not repair synchronization.
For the pinned client's compound app-state rejection with a secondary LTHash
mismatch, the read/unread bridge attempts one official full sync of the affected
collection, then calls SendAppState once more with the unchanged patch. This
rebuilds that collection's version/hash/MAC cache, not messages, read cursors,
receipts or the session; synchronized chat settings can refresh. Integrity checks
remain enabled. Failed repair/resend does not loop or replenish the per-client,
per-collection attempt budget. Publishing a different client starts a fresh budget.
A post-accepted-send fetch error never triggers this recovery.
Recovery is disabled when full-sync action-event emission is enabled. Lifecycle transitions cancel active repairs without waiting for them or changing disconnect ordering; a canceled fetch must not be followed by a resend. The existing request deadline is inherited, not restarted per step. It is not a wall-clock guarantee while waiting on whatsmeow's non-context-cancellable app-state mutex. A successful bridge result still needs real WhatsApp validation; tests do not prove service sync.
Keybindings are contextual. Press Esc to close the active menu, picker, search, viewer, reply,
or editor state.
The contact information pane keeps the conversation visible and shows a large profile photo, phone number (when known), and shared groups from the local known-group catalog. Membership is queried in the background; loading, unavailable, and empty results are shown separately. If some group queries fail, available matches remain visible with “Some groups unavailable”, including when no matches are found in the successful queries. An incomplete scan is never shown as “No known shared groups”; if every query fails, the pane shows “Shared groups unavailable”. This is not an account-wide group census. Unknown LID identities are never treated as phone numbers. Contacts without a profile photo use the illustrated default portrait; real photos still take precedence. Group and community artwork is unchanged.
At 180 columns the contact pane occupies 46 columns. Narrow terminals temporarily hide the
section rail and chat list before reducing conversation space; very small terminals show
contact details alone. Esc restores the normal layout without changing the draft. Composer
and picker input retain priority; i returns to composing, and Space a i focuses details again.
| Action | Key |
|---|---|
| Quit | Ctrl+Q |
| Toggle section rail | Space, then 1 |
| Toggle chat list | Space, then 2 |
| Toggle notifications and audio (saved immediately) | Space, then a, then n |
| Contact information (selected contact or open direct conversation) | Space, then a, then i |
| Scroll contact details / close contact pane | j / k, then Esc to close |
| 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 or start a conversation | / in the Chats list (All filter); type a name or + followed by 7–15 digits, then press Enter |
| Cycle chat filters (All, Unread, Groups, Archived) | Tab in the Chats list |
| Selected chat: mark read / unread | Space, then a, then m in the contact list |
In the contact list, press Space, then a, then m to mark the selected visible
chat as read or unread. The menu shows the next action and disables it when no
chat is selected; this toggle is not available in Status. It queues WhatsApp
chat app-state, not new message read receipts. Empty chats are supported.
Marking unread adds an indicator and includes the chat in the Unread view without
rewinding its read cursor or inventing a new-message count or mention alert.
Opening the chat clears that manual indicator without moving the existing cursor
anchor or clearing real unread messages. The manual flag is session-only locally:
it is not restored from the local database after restart, though a subsequent
WhatsApp app-state update can set it again. A queue rejection shows an error and
leaves the manual action unapplied; queue acceptance is not server confirmation.
Known limitation: the contact-menu read/unread action has only been verified to update local TUI state. Remote WhatsApp app-state sends are still attempted, but current manual validation shows no synchronization with the phone. Do not rely on WhatsApp's read/unread state reflecting this action; synchronization remains unresolved. The diagnostics and bounded recovery described above do not establish a service-level fix.
| Action | Key |
|---|---|
| Start composing | i |
| Search messages in the open chat history | / with the conversation focused; Enter accepts, Esc cancels |
| Next / previous matching message (wraps) | n / N after a chat search; j / k still navigate every message |
| Start optional Vim composer (Chats/Communities conversation only) | Space, then v |
| 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 |
With the message history focused, / searches the open chat's locally loaded text messages
using a literal, case-sensitive substring. Type a query and press Enter to jump to its newest
match, even if it is outside the viewport. The search line shows the match count and current
position, or Sin coincidencias when nothing matches. Use n for older matches or N for newer
matches (both wrap); j/k still visit every message. Esc clears the search. In the Contacts
list, / still searches contacts, and / in the composer remains ordinary text. This does not
search other chats, remote history, file captions, or media.
Consecutive photos and videos from the same sender share a main preview and
count in chat history, for both received and sent messages. Up to three narrow
slices of neighboring previews peek out to its right when space permits; the
main preview stays anchored rather than right-aligning the whole panel. Text, other
senders, date changes, deleted messages, and unread boundaries split piles.
The newest message is shown by default. j/k still visit each original
message; selecting a member brings its own preview, caption, quote, and actions
to the front. The ordered neighbor window shifts horizontally with that
selection, and reversing navigation restores its previous order; there is no
timed animation. Preview slices load through the normal media worker and do
not mark their hidden messages read. Only the front member counts as visible
for read receipts.
v starts on that member and still browses all photos/videos in the chat, not
just its pile. Status updates retain their separate cards.
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.
| Context | Action | Key |
|---|---|---|
| Composer | Send | Enter |
| Composer | Paste text, files, or an image | Ctrl+V |
| Vim composer Normal | Move cursor | h/j/k/l |
| Vim composer Normal | Next / previous word start | w / b |
| Vim composer Normal | Next / previous word end | e / ge |
| Vim composer Normal | Next / previous WORD start | W / B |
| Vim composer Normal | Next / previous WORD end | E / gE |
| Vim composer Normal | Yank to system clipboard (word/WORD motion) | yw/yb/ye/yge/yW/yB/yE/ygE |
| Vim composer Normal | Yank current line (including newline) | yy |
| Vim composer Normal | Paste system clipboard text at cursor | p |
| Vim composer Normal | Insert before / append after current grapheme | i / a |
| Vim composer Normal | Return to chat (draft kept) | Esc |
| Vim composer Insert | Return to Normal | Esc |
| Reaction picker | Move / confirm | j/k or Up/Down arrows / Enter |
| Media viewer | Previous / next | h/l or arrows |
| Media viewer | Save image or video as a file | s opens folder picker; j/k or Up/Down selects, h/Left goes up, l/Right opens folder, / filters folders; Enter edits basename, Enter saves; Esc leaves search/editing before closing |
In an editable Chats/Communities composer (including Vim Insert and message editing),
terminal paste inserts the complete text block at the cursor, preserving line breaks without
sending. Press Enter separately to submit. Bracketed paste is enabled only while that
composer owns editable input; search and other screens keep their existing input behavior.
If the terminal delivers Ctrl+V as a key instead, the existing clipboard text/file/image
handling still applies.
Save As starts in the app's current working directory. Browse folders in the viewer, then edit the
separate proposed basename and confirm. The extension is displayed but fixed from the source
media format (or a kind-based fallback). The basename must be a single component, not a path.
Folder search filters names; Esc retains the filter while returning to browsing, and entering a
folder clears it. Esc in name editing returns to browsing; Esc in browsing closes Save As.
The viewer shows the saved destination after success. Existing files are never overwritten;
choose another name if one exists.
The optional Vim composer starts in Normal mode; its border title shows Normal or Insert.
i enters Insert at the current cursor; a advances past the current grapheme within the
same line before entering Insert (and stays put at the end of a line or an empty draft).
Ordinary i composition remains unchanged. These motions move only the cursor: a word
separates letters/digits/underscores from punctuation, while a WORD is any non-whitespace
run. In Normal mode, y waits for a supported motion or another y; Esc cancels it.
Yanks copy to the system clipboard, without changing the draft or cursor. In Normal mode,
p inserts the clipboard's text at the cursor, even after yy; it does not use a Vim register
or Vim's after-cursor/linewise put positioning. p does not attach images or files; use
Ctrl+V while editing to paste those. There are no registers or counts, and this is not full
Vim emulation. Search, substitution, and deletion are not available here. Files pasted with
Ctrl+V are queued as attachments; text becomes the caption of the first attachment.
Queued images (including clipboard images) and videos show compact still previews
while composing, before you send. Up to three previews are prepared at a time;
video frames require FFmpeg with seekable fd: input support. The preview reads
the selected local file without changing it or creating JPEG sidecars. Filenames
remain the fallback for missing, corrupt, unsupported, or failed media. On small
terminals, previews and attachment labels give way to the text and cursor;
additional attachments may be summarized. Sending and captions are unchanged.
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=1Run the Go test suite:
cd whatsrust/lib
go test ./...Continuous integration runs format checks, Rust and Go builds/tests, and installer archive tests on both Linux and macOS for pushes to main and pull requests. Nix build and dev-shell checks run on Linux. 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.
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.
MIT © 2026 andiveli. See LICENSE.
Third-party components are listed in THIRD_PARTY_NOTICES.md.