matterhorn is a terminal client that tries to match the web client

The stated goal is parity, not a subset

The design philosophy section is unusually explicit about what the project is trying to be. The overall goal is to build a terminal client that provides the same basic feature set as the web client, and the README says this is reflected in the state of the client, the issue backlog and the content of the wiki feature design discussions. The intent is to add web client features to the extent that they can be added sensibly in a terminal setting, in a way that minimises surprise for web client users migrating while still giving the best terminal experience the maintainers can think of. That can mean adding a web feature but changing its design to something better suited to a terminal, omitting aspects of web features that rely heavily on mouse or DOM idioms, or adding a web feature and deviating slightly on specific behaviours. The last sentence of the section is the most useful for a user, that if you are used to a web client feature and do not see it, it is probably because they have not gotten to it yet.

The version number tells you which server it fits

The versioning scheme is unusual and worth understanding before you download anything. A Matterhorn version string has the form ABBCC.X.Y, where ABBCC corresponds to the lowest Mattermost server version expected to be supported by the release, so a release that supports server version 1.2.3 carries the prefix 10203. The README gives the mapping to use in practice, that version ABBCC.X.Y matches Mattermost server version A.BB.CC, so a server on 3.6.0 means matterhorn version 30600.2.4. The X.Y part is the project's own namespace, and the rule is that if the server version changes, X.Y should be 0.0, otherwise the first component increments for major code or functionality changes, and the second component changes only for security fixes or other bug fixes. There is a worked example of the range, since matterhorn 50200.X.Y supports server versions 5.2 through at least 5.8. The current releases follow the pattern, 90000.0.1 on 2024-08-27, 90000.1.0 on 2025-03-10 and 90000.1.1 on 2025-10-08.

Getting the binary, and the one platform caveat

Pre-built binary releases are provided for some platforms, and the download list is the release list on the repository page, with the instruction to pick a binary that matches your server version. To run it, you unpack the archive and run the matterhorn binary inside it, and help is available with the --help or -h flag:

$ matterhorn --help
$ matterhorn

On first run you are prompted for your server URL and your credentials, and the instructions are to paste the Mattermost URL from your web client into the Server URL box and enter your credentials, with the User Guide in the docs directory covering the details for each kind of supported credential. For most of the binary releases no additional packages are needed and they should work out of the box, with one exception called out for CentOS Stream 8, where the ncurses-compat-libs package must be installed. There is also a third-party Snap package maintained by someone else, with the repository and the Snapcraft page both linked, which is worth distinguishing from the official builds because it is a different maintenance path.

What a chat client has to do, and does

The feature list is long enough to be a useful answer to the question of whether a terminal client can be taken seriously. On the server side there is channel creation, deletion and membership management, and support for multiple teams, plus message posting, editing, replying and deletion. On the reading side there is Markdown rendering, participation in threads through the thread window, and syntax highlighting of fenced code blocks in messages, which the README says works best in 256-colour terminals, along with spell-checking via Aspell. On the writing side there is a message editor with kill and yank buffer and readline-style keybindings, optional live preview during message editing, optional smart quoting for efficient Markdown entry, the ability to edit messages with $EDITOR, and support for attachment upload and download. Two features are quietly about other people's attention, adding and removing emoji post reactions, and flagging and unflagging of posts, which are then viewable with M-8 or through the /flags command.

Tab completion is the interaction model

The completion behaviour is the part that shows how the client is meant to be used, and it is worth reading as a list because each entry is a small idea about terminal interaction. Typing @ and pressing Tab cycles through username matches, typing ~ cycles through channel names, typing / cycles through commands, and typing : followed by some text shows and cycles emoji matches. Typing three backticks begins a code block and Tab then cycles through the available fenced code block languages, which is a nice touch because it is the one completion in a chat client that produces a document rather than a name. Channel switching has its own optimized modes, with M-a, M-s and C-g. There is also convenient URL opening with the local browser, yanking of verbatim content from messages into the system clipboard, optional mouse support, rebindable keys with a keybinding list in the docs, multiple colour themes with customization, and secure password and authentication token entry through an external command such as the macOS keychain, so a credential never has to be typed into the terminal in the clear.

Proxies, notifications and the parts that touch your system

Three features reach outside the terminal, and each is configured rather than built in. SOCKS 4 and SOCKS 5 proxies are supported through the ALL_PROXY and HTTPS_PROXY environment variables, with NO_PROXY also supported, and the README is explicit that plain HTTP proxies are not yet supported, which is the kind of limit worth knowing before you configure one. Custom notifications are handled by notification scripts, configured through the activityNotifyCommand setting and documented in docs/notification-scripts.md, with a notification-scripts/ directory in the repository holding the examples. And secure credential entry is delegated to an external command such as the macOS keychain, which is the right way to handle a token in a client that is otherwise a terminal program. The repository also carries a client-scripts/ directory alongside the notification scripts, and the whole thing is a Haskell project with a cabal file, a Setup.hs, a cabal.project, a build.sh, a run.sh, a submodules/ directory with its own .gitmodules, and a syntax/ directory.

Contributing, and the Haskell bar

The contributing section is unusually practical, and the first item tells you what you are up against. If you are new to Haskell and unsure how much Haskell you need to know to contribute, the project keeps a list of Haskell skills needed in docs/HASKELL.md, which is a way of saying that a patch here is a Haskell patch. The branching rule is specific, base all patches against the develop branch unless you are specifically fixing a bug in a released version, in which case master is fine, and the same applies to submodules that have a develop branch. And the rule for large work is a design and vision discussion before any coding, with a GitHub issue as the place to hash it out, because the maintainers say they are interested in discussing usability and interface questions rather than just accepting a patch. The help channels are the FAQ and the User Guide in the docs directory, the built-in /help command, the command list and keybinding list documents, the Mattermost community server channel for the developers, and the issue tracker on the repository. The licence is BSD 3-Clause.

Editorial conclusion

matterhorn is the right client if you live in a terminal and your team runs Mattermost, because the feature set is deliberately not a reduced one, and because the version scheme makes it obvious which build pairs with which server before you install anything. It is the wrong choice if your day is spent in a graphical client and the terminal is where you go to run one command, and it is a poor fit if you need the web client's mouse-driven workflows, since the project says it omits features that rely heavily on mouse and DOM idioms. Before you install, work out the server version you run and pick the matching binary from the release list, because the version string encodes it, and read the User Guide section on credentials, since the supported credential kinds are more than one and the choice determines whether your token is stored securely or typed in plain.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. matterhorn-chat/matterhorn on GitHub
4. README
5. Releases