whatscli: WhatsApp in the terminal, without a browser

The web app API, without the web app

The two libraries underneath explain the whole design. The client is built on the Go implementation of the WhatsApp multi-device protocol, and the interface is a terminal user interface library, so the application is a text-mode program with a chat list, an input field and a message pane.

The feature list is short and practical. Sending and receiving messages in a command line application. Connecting through the Web App API without a browser, which is the point of using the protocol library rather than a wrapper around a web session. QR code for simple setup. Downloading and opening image, video, audio and document attachments, and sending the same kinds of file back. Colour customisation. Basic group management. Desktop notifications. And binaries for Windows, Mac, Linux and Raspberry Pi.

That last item is a small signal about the audience. A Raspberry Pi build means the author expects people to run this on a small always-on machine, which is exactly the use case where a browser would be the wrong shape.

The readme has a caveats section that deserves as much attention as the features, and the framing is that these are things you might expect to work that do not. Message history depends on what WhatsApp syncs to companion devices, and may need the backlog command to pull more. There is no automation of messages and no sending of messages through shell commands. And the author states plainly that Meta does not endorse or like these kinds of applications and that they are likely to break when WhatsApp changes things in their web app.

That last line is the honest summary of the project, and it is better to read it before installing than to discover it later.

Installing, and the two routes that may be stale

The installation section separates the fresh route from the package managers, and the warning is explicit.

The recommended path is to download a release, put the binary in your path if you want it there, and run it, or double click it. On start it tries to connect to the WhatsApp server to log in, and you scan the appearing QR code with the phone. If you cannot scan it in time, restart the application, and if you cannot see the whole code, reduce the font size of the terminal or enlarge the window, which is a small usability detail that matters because a QR code you cannot read is a QR code you cannot use.

The package manager routes are listed separately, with a warning that the installed version might be out of date. On macOS there is a Homebrew tap:

brew install normen/tap/whatscli

and on Arch Linux there is an AUR package. The distinction between the two sections is a good one, because a tap or an AUR package is convenient and can lag, while a release download is what you actually want if you want the code the author just wrote.

After the first scan the chats are populated and the application can log in automatically on subsequent starts. Logging out completely is a command,

Working the interface

The usage section is written for somebody who has never seen a terminal chat client, and the details are the good part.

You select a chat on the left and type in the input field at the bottom to send a message, and the tab key switches between the chat list and the input field. Commands go in the same input field and are prefixed with a slash by default, so a command such as sending an image by path works, and the in-app help lists the rest.

A detail that will save you an argument: when a path is given for a command you do not need to surround it in quotes even if it contains spaces, and you should not escape the spaces with backslashes either, which is what a copy and paste from macOS tends to do.

There is a message selection mode, entered with the control and w combination, which lets you select a single message and act on it. Pressing the letter o with a message selected opens any attachment through an external application, which is how you get an image out of a conversation and into an image viewer.

Some commands, such as adding and removing contacts, need a user id. The readme explains the workflow: you copy the id of a selected chat or message to the clipboard with control and c, then paste it into the input with control and v.

Most of the information, all the commands and all the key bindings are available in the application itself, through the help and commands commands, which is the right place for them to live since the bindings are configurable.

Images, attachments and notifications

Three features deserve their own note, because they are the ones a terminal client has to work around.

Images are displayed using external programs that convert the image into characters. The author found that a particular tool works well for jpeg images and is available through package managers on most systems, while being blunt that the image quality leaves a lot to be desired. A better option is named for true-colour display, which renders images in a way that is already quite recognisable. The command and its parameters are configurable through the show command setting in the configuration file, and the help command shows where the configuration file lives.

The second feature is the attachment workflow, which is a consequence of the first. Since images are converted by an external program, the same mechanism works for opening any attachment through an external application, and the readme makes that explicit in the message selection section.

The third is notifications. Basic desktop notifications are supported through a beep library, and are enabled with a setting in the configuration file. There is also a setting to ring the terminal bell instead of sending a desktop notification, which is the better choice if you run the client in a terminal multiplexer on a remote machine and do not want notifications on the local desktop.

The configuration file holds most of the key bindings, the colours and the other options, and the same help command shows its location.

The architecture: one goroutine for the network, one for the interface

The development section explains the structure, and it is the part that shows how the project is put together.

The main file holds most of the user interface elements, built around a terminal application running on the main routine, and it uses a keymap configuration library. Apart from the interface it manages the selection of messages in the current chat and displays the messages and the chat list that the session manager sends.

The session manager runs as a separate goroutine to receive messages from the protocol library, which in turn runs the websocket connection to the WhatsApp server. It receives the messages and the commands from the interface through channels that it drains on its main routine, and then updates the interface through a handler interface. The stated purpose is thread-safe management of the connection and the data while the interface and the network connection run separately, which is the correct way to keep a terminal interface from stalling while a socket is busy.

The session manager is described as designed in an object-like way, and the message database is similar and somewhat linked to it. The author notes that in theory the session manager could be run multiple times for multiple accounts, or that a different implementation could connect to a different service such as Telegram. That is a design with ambitions beyond a single chat client, and the fact that the interfaces live in a separate file for the messages means the swap is a matter of implementing an interface rather than rewriting the application.

The configuration is a singleton struct in a settings file, loaded at start through an INI library, and the stated benefit is that adding a configuration item with a default value is easy.

Maintenance, licensing and the project layout

The project is a personal project that the author describes as his first attempt at writing something in Go, and the readme invites contributions with the note that some areas marked as unfinished can still be improved but mostly work.

The release history shows regular work: version 1.1.4 in April 2026, 1.1.5 in June and 1.1.6 in August, with the last push on 2026-08-08 and the repository not archived. The module requires Go 1.25.

The licence is stated in the readme as MIT, and the readme adds a line that is worth quoting for its honesty about what that means in practice, that it gives you all freedom except for slapping your name on it. The repository listing does not record a licence, so check the licence file rather than assuming.

The build is a small makefile with the expected Go targets, including a release target that runs a shell script in the repository, and the readme says that with a recent version of Go you can simply use the Go build and run commands instead. The top level of the tree is a chat package, a QR code package, a configuration directory, a documentation directory with the screenshot, the main file, and the module files.

The dependency list also tells you what the interface is made of: a terminal cell library, a QR code generator, a clipboard library for the system, a SQLite driver for the message database, a toast library for the notifications, an INI parser for the configuration, and the protocol library itself, which is the only real heavyweight in the list.

Editorial conclusion

whatscli suits somebody who lives in a terminal and wants to read and send WhatsApp messages without keeping a browser tab open, especially on a small machine or over a slow connection. It is a poor fit if you want to script WhatsApp, because the readme says plainly that there is no automation and no sending of messages through shell commands, and it is a poor fit if you need message history, which depends on what the phone has synced to companion devices. Before you rely on it, read the caveats section, and treat the pairing as something that may need repeating when the upstream web app changes.

Frequently asked questions

Official sources

1. Issues
2. normen/whatscli on GitHub
3. README
4. Releases