Terminal client for the Mattermost chat system
|Latest on Hackage:||40700.0.0|
This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow stackage.org to host generated Haddocks.
Matterhorn is a terminal client for the Mattermost chat system.
New Release Notifications
Get notified about new Matterhorn releases by following our Twitter account!
We provide pre-built binary releases for some platforms. Please see the release list to download a binary release for your platform that matches your server version:
To fetch a release and run Matterhorn, run the following commands (where
PLATFORM match your setup):
wget https://github.com/matterhorn-chat/matterhorn/releases/download/<VERSION>/matterhorn-<VERSION>-<PLATFORM>.tar.gz tar xf matterhorn-<VERSION>-<PLATFORM>.tar.gz cd matterhorn-<VERSION>-<PLATFORM> ./matterhorn
When you run Matterhorn you'll be prompted for your server information
and credentials. At present
matterhorn supports only username/password
ABBCC.X.Y matches Mattermost server version
For example, if your Mattermost server version is
3.6.0 then you
would download matterhorn version
30600.2.4. See Our Versioning
Scheme for details.
For configuration options you have two choices:
- Interactive configuration entered on each program run
- Configuration via stored settings in a config file
The first option is useful when trying out the program because you can
get up and running without worrying about making a configuration. Once
you're ready to make your settings persistent, they can be added to
a configuration file. An example configuration file can be found at
sample-config.ini. Any settings omitted from the configuration will be
obtained interactively at startup.
When looking for configuration files, matterhorn will prefer
config.ini in the current working directory, but will look in the
typical XDG configuration directories (you'll probably want to use
$HOME/.config/matterhorn/config.ini) and as a last resort look for a
Using the Client
The user interface has three main areas:
- Left: list of channels you're in, and list of users in your team and
their statuses (
×means Do Not Disturb, and an absent sigil means offline)
- Right: messages in the current channel
- Bottom: editing area for writing, editing, and replying to messages
You can use built-in keybindings or
/cmd-style commands to operate
the client. To see available keybindings and commands, use the default
F1 or run the
/help command. Keybindings may include
modifiers such as Control (indicated with a
C- prefix) or Meta
(indicated with a
M- prefix). If your keyboard has an
Alt key, that
will work as
Meta. If it does not, you may be able to configure your
terminal to provide
Meta via other means (e.g. iTerm2 on OS X can be
configured to make the left Option key work as Meta). Keybindings can
be customized in the configuration file; see
/help keybindings for
To join a channel, use the
/join command to choose from a list of
available channels. To create a channel, use
/create-channel. To leave
a channel, use
To create a private group chat amongst yourself and other users, use the
/group-msg command, e.g.,
/group-msg user1 user2.
To see the members in the current channel, use the
To send a message, type it into the editor and press Enter to send.
To send a multi-line message, toggle multi-line mode with the default
M-e. Markdown syntax is accepted.
To edit your current message in an external editor (
$EDITOR), use the
default binding of
To preview the message you're about to send while you compose it (e.g.
to check on how your Markdown syntax will be rendered), toggle preview
mode with the default binding
To change channels, use
/focus or one of the default bindings
C-p (previous channel),
C-g (fast channel switch).
To directly message another user, use
C-g channel switching mode does a substring match of the input text on
the channel and usernames; metacharacters
$ at the beginning
or end of input, respectively, anchor the match in case of multiple
matches. The cursor in this mode is usable with
To switch to the channel you were in prior to the current channel, use
the default binding
M-s (swap). The most recent channel is marked in
the channel list with a "
To switch to the next channel with unread messages, use the default
To quickly show a list of URLs mentioned in the current channel and then
open one in your local browser, use the default binding of
urlOpenCommand configuration setting.
To edit, delete, flag, or reply to a message, select a message with
the default binding of
C-s. Use the default binding of
cancel these operations.
Messages that have been flagged can be viewed with either the
M-8. This view allows you to select and unflag particular
messages, as well.
To enable spell-checking in the message editor, install Aspell and set
True in your configuration. To override Aspell's
choice of master dictionary, set the
aspellDictionary option to the
name of the dictionary you'd like to use.
- Channel creation, deletion, and membership management commands
- Optimized channel-switching modes:
- Message posting, editing, replying, and deletion
- Markdown rendering
- Convenient URL-opening with local browser
- Secure password entry via external command (e.g. OSX keychain)
- Yank verbatim content from messages into the system clipboard
- Preview message rendering before sending
- Optional smart quoting for efficient Markdown entry
- Edit messages with
- Rebindable keys (see
- Message editor with kill/yank buffer and readline-style keybindings
- Tab-completion of usernames, channel names, and commands
- Spell-checking via Aspell
- Syntax highlighting of fenced code blocks in messages (works best in 256-color terminals)
- Flagging and unflagging of posts, which are then viewable with
- Support for SOCKS 4 and 5 proxies via the
HTTPS_PROXYenvironment variables. (Plain HTTP proxies are not yet supported.)
- Multiple color themes with color theme customization support
Spell Checking Support
aspell to perform spell-checking of your message
input. To use this feature:
aspelland ensure that your installation includes dictionaries corresponding to your
LANGsetting. To check this, ask
aspellto check some input:
$ echo stuff | aspell -a Error: No word lists can be found for the language "en". $ echo $LANG en_US
If Aspell succeeds, the output will look like this:
@(#) International Ispell Version 3.1.20 (but really Aspell 0.60.6.1) *
- Enter any message input in the message editor in
matterhorn. After a short delay after you stop typing, misspelled words will turn red.
matterhorn is built with the provided
install.sh script, which
git and an appropriate
(Although the name suggests installtion, this will just do a build in
dist-newstyle.) This script will pull the appropriate repos and build
the application. This is required for building Matterhorn since clones
of some of our other dependencies may need to be locally available in
deps/ in case important changes to those dependencies have not yet
Our Versioning Scheme
Matterhorn version strings will be of the form
ABBCC.X.Y where ABBCC
corresponds to the Mattermost server version supported by the release.
For example, if a release supports Mattermost server version 1.2.3, the
ABBCC portion of the
matterhorn version will be
portion of the version corresponds to our own version namespace for the
package. If the server version changes,
X.Y SHOULD be
the first component should increment if the package undergoes major code
changes or functionality changes. The second component alone should
change only if the package undergoes security fixes or other bug fixes.
If you decide to contribute, that's great! Here are some guidelines you should consider to make submitting patches easier for all concerned:
- If you want to take on big things, let's have a design/vision discussion before you start coding. Create a GitHub issue and we can use that as the place to hash things out. We'll be interested to discuss any usability / UI, performance, or compatibility issues.
- Please make changes consistent with the conventions already used in the codebase.
- We follow a few development practices to support our project and it
helps when contributors are aware of these. Please see
PRACTICES.mdfor more information.
Frequently Asked Questions
- Q: Does matterhorn support Gitlab authentication?
- A: No. But we would be happy to work with contributors who are interested in investigating what this would take and/or implementing it. See the Contributing section for details.
This release supports Mattermost server version 4.7.
/focus command with no arguments now starts channel selection
mode, equivalent to the default binding of
/join command now accepts an optional channel name argument. If
provided, the named channel is joined (#361).
A new user browser was added! The user browser presents a list of
users and the ability to search users by name. The new user list
powers some new and existing commands:
/msg command is used to browse known users and select a
Enter to begin a private chat session with the selected
/add-user command is used to add users to the current
channel. The list shows users who are not already members of the
Enter adds the selected user to the channel.
/members command now shows a browsable user list of
members of the current channel.
Enter begins a private chat
session with the selected user.
urlOpenCommands are now reported as error messages rather
than informative messages.
More login-related exceptions are now displayed in a more readable
format on the login screen (#358).
Channel selection mode now prefers an exact match as the initial
cursor selection if one exists (#356).
Replies now indicate the correct parent message in the message list.
* The multi-line editor help message now shows the active binding
Performance improvements: Matterhorn's reconnection handling was improved to more reliably fetch messages that arrived while the client was disconnected. Startup performance was improved by reducing redundant post and user metadata fetches when loading channel messages.
Other fixes: The multi-line toggle help message now shows the active binding. Slash commands now support multi-line input. Previously only the first line was passed as the command input. * Matterhorn now updates channel view status on updates from other clients (#342)
This release supports Mattermost server version 4.6.
Rebindable keys are now supported! See
/help keybindings for
details. Matterhorn also checks for conflicting bindings on startup.
The user status list now supports the Do Not Disturb status (shown as
User typing notifications are now supported. These are off by default
but can be enabled with the
setting. Enabling the feature causes Matterhorn to produce such
notifications for the server and to display typing indications from
other users. Thanks to Abhinav Sarkar for this feature!
Matterhorn now remembers which channel was visited when the client is
closed and returns to that channel on startup. Thanks to Abhinav
Sarkar for this feature!
/message-preview now toggles message preview mode in addition to
Bug fixes: * New post reactions no longer cause a post to be indicated as "(edited)" (#333)
* The channel list shown by
/join now also displays the channel
purpose for each channel when possible.
Performance improvements: * Matterhorn now has much lower input latency on servers with very large numbers of users due to user list rendering performance improvements.
Miscellaneous: This release now uses only version 4 API endpoints, consistent with the upstream deprecation of version 3 API endpoints in the 4.6 release. Startup requests are now performed concurrently to improve performance (#347, thanks to Abhinav Sarkar) * Channel header strings containing newlines are now rendered more effectively: newlines are converted to spaces. This behavior more closely matches the web client, too.
This release supports server version 4.4.
The active color theme can be customized by creating a theme
customization file and setting the new
option. This setting lets you override any foreground color,
background color, or style of any aspect of the Matterhorn interface.
For details on the format of the customization file, please see the
"Themes" help in Matterhorn with the
/help themes command.
Edited posts are now displayed with a trailling "edited"
marker. This change includes some new behavior and a new
When you visit a post that has recent edits, the "edited" marker
will be highlighted. This highlight can be dismissed in the same
way as the "New Messages" cutoff, using the
This feature can be turned off using by setting the
showOlderEdits configuration option to
/remove-user command removes a user from a channel.
/group-msg command creates a new private group channel
including several users.
/search [term] command searches the chat history for posts
that include the provided text and displays those posts in an
overlay. Thanks to @abhin4v for this change!
Matterhorn now includes embedded hyperlinks using terminal escape
sequences in terminals that support them. For more information on
terminal support for hyperlink escape sequences, please see this
and its associated discussion.
The width of the channel list (in columns) is now configurable with
channelListWidth, which defaults to 20.
urlOpenCommand can now be an interactive terminal-based
program (such as a terminal-based web browser) but this requires
the configuration option
urlOpenCommandIsInteractive to be set to
True. This defaults to
False and should not be changed if the
urlOpenCommand is not a terminal-based program.
The current selection in channel select mode can be moved forward
and backward with
C-p. (fixes #139)
Quotation blocks now include visible characters in addition to
We now honor the server's notification settings for channels.
Bug fixes: New direct-message channels are properly added to running sessions (fixes #264) No more reporting of "resource vanished" exceptions (fixes #116) Missing editing keybindings now included in edit binding list (fixes #139) Websocket message parse failures no longer result in crashes (fixes #297) The sidebar no longer shows deleted users (fixes #316) Tab-completion no longer includes deleted users (fixes #320) User status updates are now rate-limited (fixes #282) Private channels can be deleted successfully (fixes #304) External commands now run in the background in their own thread and do not block the main UI (fixes #270) Channel renaming is honored at runtime and does not require a restart (fixes #324) Group channel show/hide preferences are observed, which in practice means a user can now 'leave' a several-user group channel New channels will not appear twice in the sidebar (fixes #327) * New messages to previously-hidden group channels will cause the group channel to be shown again (fixes #326)
PRACTICES.md is now listed in extra-doc-files.
Three scripts usable with the
/sh command are now listed in
cowsay runs the message text through the
cowsay shell command
and formats the output as a verbatim block. This command requires
cowsay command-line program to be installed externally.
figlet runs the message text through the
figlet shell command
and formats the output as a verbatim block. This command requires
figlet command-line program to be installed externally.
rot13 runs the trivial ROT13 subsitution cipher over the
message text and otherwise passes it through unchanged.
New features: Messages that start with a block-level element now get laid out so that the block level element appears underneath, rather than to the right of, the user name. This helps with long usernames such as bots. Thanks to @kellymclaughlin for this change. Code blocks with fencing now display the language when syntax highlighting is active. In channel scroll mode, Up/Down arrow keys scroll by just one row All channel and user data are now fetched more efficiently on startup for greatly improved startup time.
/members command now only shows active users (fixes #315)
Reset edit mode after handling commands and message input, provide
reply context when running commands (fixes #305)
Allow all unknown client commands to fall through to server (fixes
Improve uniqueness comparisons for URL lists
Bug fixes: * Attachments no longer appear in duplicate for edited messages.
Package changes: * CHANGELOG.md is now listed in extra-doc-files.
Package changes: Upgraded mattermost-api to 40000.0.1. Upgraded mattermost-api-qc to 40000.0.1.
emoji_added websocket events rather than crashing due to
JSON decode failures (#296)
channel_viewed websocket events from 4.0 servers
channel_id value no longer cause a client crash
* mkrelease.sh: use correct bindist file extension (#295)
This release supports server version 4.0.
Package changes: Upgraded mattermost-api to 40000.0.0. Upgraded mattermost-api-qc to 40000.0.0.
/focus your own DM channel no longer trigger a server
error (fixes #294)
Message edits now properly restore message reactions and attachments
DM channels with topics now display those topics in addition to the
DM channel user identification.
Rendering of attachments regressed in 31000.0.0 and is now fixed
so that attachments are displayed beneath, not to the right of, their
Markdown image alt text is now rendered when available and Markdown
images are now available in the C-o URL list (fixes #285)
Added a new configuration setting,
determines whether the status of Matterhorn's asynchronous work queue
is displayed in the interface. This setting is mostly for developers
but can be a helpful diagnostic tool. When enabled, the setting
causes the async queue length to appear in the lower-right corner of
* Added a new configuration setting,
unsafeUseUnauthenticatedConnection, which causes Matterhorn to use
a non-HTTPS connection when connecting to the configured host and
port. As the sample configuration file says, use this only if you
know what you are doing.
* Added support for 4.0's
This release supports server version 3.10.0.
Package changes: Upgraded mattermost-api to 31000.0.0. Upgraded mattermost-api-qc to 31000.0.0.
New features and keybindings: Matterhorn now supports Flagged Posts. To use this feature: Press M-8 or use the /flags command to show a list of your flagged posts. Within that view, 'f' will unflag a selected message. In message selection mode in channels (C-s), 'f' will flag/unflag the selected message. Flagged posts appear with a flag marker "[!]" next to the author's username. Syntax highlighting of fenced code blocks is now supported in 256-color terminals. Code blocks must provide the langauge hint using the same syntax as supported by the web client. Spell checking of user input is now supported using Aspell. To use this feature: Install the Aspell binary and dictionaries on your system. Set enableAspell = true in your Matterhorn configuration. Optionally, set aspellDictionary to the name of the Aspell dictionary you want to use (this is only necessary if you want to override your LANG setting, which is typically sufficient) Once user input is entered into the input area, a short delay after typing stops, a spell check will highlight any misspelled words. Home and End now move the cursor as usual in editor while in normal mode, and also navigate the message list while scrolling. Matterhorn now displays the mention count in the channel sidebar to mimic the web client behavior and highlights channels with at least one mention in magenta in the sidebar.
Bug fixes and improvements: Configuration file values can now use quoted string syntax (fixes #269) The channel switch mode prompt now mentions anchors. The URL opening command is now run asynchronously. Input history files are now saved with an appropriate file mode (fixes #218) Fixed a bug that caused users created after a session began not to appear in the sidebar. Help topics (valid arguments to /help) are now displayed in the main help UI (fixes #225) Message deletion now also deletes replies to the deleted message (fixes #257) On channel deletion, leave before deleting to avoid a server error. URLs in the URL list are now displayed in the same order in which they appear in messages (fixes #250) User identification now appears in DM channel headers. Numbered lists now render starting at first specified number (fixes #243) The login screen now displays validation errors for hostname and port inputs when appropriate (fixes #242) * Channel select inputs that have an exact match no longer require ^/$ anchors.
This release supports server version 3.8.2. This release is our first official public release.
Package changes: Removed stale array and data-default dependencies Increased lower bound on base dependency to 4.8 to relect our GHC testing.
Improvements: Subprocess error logs are now only created on demand. Previously we created them on startup before any subprocess errors had occurred. We now provide a QuickCheck test for some infrastructure.
Bug fixes: Fixed a bug whereby some resize operations would cause a program crash by triggering an unsafe mutable vector operation in Vty. New user creation is now handled successfully and no longer requires a client restart to function reliably. Previously bad behavior included not coloring new users' names and not showing new users' names at all on their messages. Message selection mode is no longer blocked by errors and other non-post content. Subprocesses that fail to run are now consistently mentioned in the subprocess error log.
This release supports server version 3.8.2.
Package changes: Relax constraint on containers to allow 0.5.7 or greater. Upgraded mattermost-api to 30802.0.0.
Bug fixes: The help interface now updates properly when showing either the main help window or the scripts help window. Attachments are now saved asynchronously. Attachments are now opened without using the browser, thus removing our dependency on a valid browser session with the server (fixes #128) Editing state is now saved before switching history entries (fixes #210) * Messages with unknown authors trigger a user metadata fetch (fixes #205)
New keybindings: C-o now opens the URL list while scrolling through channel messages. C-c now cancels channel selection in C-g mode
UI changes: Channel scroll mode keybindings were added to the help page. We no longer perform string highlighting on the contents of Markdown code spans in messages. On startup, only the scrollback for Town Square is fetched to improve performance. Scrollback for other channels is fetched on demand. We now use the channel sigil "~" rather than "#" to match the web client behavior, and highlight ~-prefixed channel names (fixes #204).
This release supports server version 3.7.1.
Matterhorn now has basic support for 3.7's new "group channel"
feature. If other users add you to a group channel, it will appear in
the sidebar with the member usernames listed (e.g. "#bob, sue, ...").
Creation of group channels will be supported in a future release.
urlOpenCommand program produces output on standard output
or standard error, this output is now logged and a message is posted
in the current channel with the path to the log file. This feature
prevents the URL open command from poisoning the terminal state with
/members command to show current channel membership.
Channel header changes from other users will now cause the channel
topic string to update.
/delete-channel command to delete the current channel.
Markdown rendering now puts empty lines between adjacent block
elements of the same variety to improve readability.
Bug fixes: Message selection now only supports reply/edit/delete on normal posts (fixes #174) C-n/p now only change channels when a non-DM channel is selected (fixes #82) We now handle new user events (fixed #111) On channel change we now always reset the channel list to scroll to the top (fixes #138) When a draft message is left in the editor when changing channels, a new sigil ("»") appears for the previous channel instead of the usual "#" to indicate this. The help interface now resizes properly all the time.
Performance improvements: * On startup, all channel contents are fetched asynchronously. Town Square fetches are prioritized. These changes drastically improve startup time, even on fast connections.
Documentation changes: * The README now includes a feature list, a brief feature overview for new users, and a section on how to contribute.
Package changes: Upgraded mattermost-api to 30701.0.0. Binary releases now include the copyright and licensing information for all dependencies.
* Added preemption support for asynchronous work queue processing.
doAsync(With) now both take an
New editing keybindings: C-w, M-Backspace now delete the word to the left of the cursor. M-d deletes the word to the right of the cursor. C-k now kills text from the cursor to the end of the line and copies to an internal buffer; C-y pastes from said buffer. C-b, C-f move back and forward by one word, respectively.
Many editing keybindings are now present in their own Help page section.
Package changes: Upgraded text-zipper to 0.10. Upgraded mattermost-api to 30600.2.2.
Bug fixes: Message-yanking failures due to missing programs (e.g. xclip) no longer trigger an unhandled exception (fixes #170) Users that are not members of the current team are now hidden from the user list (fixes #161) User statuses in the sidebar are now periodically refreshed Supported server commands now appear on the help screen (fixes #162) Files containing non-UTF-8 content no longer trigger unhandled exceptions when being read by matterhorn (fixes #168) Updated repository URL in error message about reporting problems (thanks @tommd)
- Improved formatting of message attachments so that their filenames are shown. Previously only their hash identifiers were displayed. This change also entails asynchronous fetching of attachment metadata.
- Upgraded to mattermost-api 30600.2.1.
Fixed a bug that caused message selection mode to trigger a Vty crash when a message being rendered was larger than half of the area available for the message list.
Added a new message selection mode. This mode provides access to four new features: replies, edits, deletion, and verbatim text yanking. To enter this mode, use the default binding of C-s (and cancel with Esc). The resulting cursor can be used to select messages in the current channel and perform the following actions on them:
- y: for messages with any verbatim text, yank the verbatim text to the first verbatim block in the message to the system clipboard (works on Linux and OSX)
- r: reply to the selected message. To cancel a reply, press C-c or Esc.
- e: for messages written by the current user, edit the selected message. To cancel an edit, press C-c or Esc.
- d: for messages written by the current user, delete the selected message (with a confirmation).
- o: for messages containing URLs, open all URLs in the selected message.
- j/k/up/down/pgup/pgdown: change the selected message cursor position.
Added a C-r binding to begin a reply to the most recently posted message in the current channel.
M-e now toggles multiline editing mode rather than just enabling it. Previously, Esc toggled it off.
Upgraded to mattermost-api 30600.2.0.
Upgraded to mattermost-api 30600.1.0. This fixed /me and /shrug server-side command execution failures.
Initial versioned release for server version 3.6.0.