matterhorn

Terminal client for the Mattermost chat system

Latest on Hackage:40600.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.

BSD3 licensed and maintained by

Hackage Build
Status

Matterhorn is a terminal client for the Mattermost chat system.

New Release Notifications

Get notified about new Matterhorn releases by following our Twitter account!

https://twitter.com/matterhorn_chat

Quick Start

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:

https://github.com/matterhorn-chat/matterhorn/releases

To fetch a release and run Matterhorn, run the following commands (where VERSION and 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 authentication.

Note: Version ABBCC.X.Y matches Mattermost server version A.BB.CC. 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.

Configuring

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 globally-accessible /etc/matterhorn/config.ini.

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 online, - means away, × 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 binding of 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).

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 /leave-channel.

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 /members command.

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 binding M-e. Markdown syntax is accepted.

To edit your current message in an external editor ($EDITOR), use the default binding of M-k.

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 M-p.

To change channels, use /focus or one of the default bindings C-n (next channel), C-p (previous channel), C-g (fast channel switch).

To directly message another user, use /focus or C-g.

C-g channel switching mode does a substring match of the input text on the channel and usernames; metacharacters ^ and $ at the beginning or end of input, respectively, anchor the match in case of multiple matches. The cursor in this mode is usable with C-n and C-p.

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 "<" indicator.

To switch to the next channel with unread messages, use the default binding M-a.

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 C-o and configure the 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 C-c to cancel these operations.

Messages that have been flagged can be viewed with either the /flags command or 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 enableAspell to 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.

Features

  • Channel creation, deletion, and membership management commands
  • Optimized channel-switching modes: M-a, M-s, and C-g
  • 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 $EDITOR
  • 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 M-8 or /flags
  • Support for SOCKS 4 and 5 proxies via the ALL_PROXY, HTTP_PROXY, and HTTPS_PROXY environment variables. (Plain HTTP proxies are not yet supported.)
  • Multiple color themes with color theme customization support

Spell Checking Support

Matterhorn uses aspell to perform spell-checking of your message input. To use this feature:

  • Install aspell and ensure that your installation includes dictionaries corresponding to your LANG setting. To check this, ask aspell to 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)
    *
  • Set enableAspell to True in your config.ini
  • Enter any message input in the message editor in matterhorn. After a short delay after you stop typing, misspelled words will turn red.

Building

matterhorn is built with the provided install.sh script, which requires git and an appropriate ghc/cabal installation. (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 been released.

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 10203. The X.Y portion of the version corresponds to our own version namespace for the package. If the server version changes, X.Y SHOULD be 0.0. Otherwise 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.

Contributing

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.md for 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.

Changes

40600.0.0

This release supports Mattermost server version 4.6.

New features: 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 showTypingIndicator configuration 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!

New commands: * /message-preview now toggles message preview mode in addition to default M-p keybinding.

Bug fixes: * New post reactions no longer cause a post to be indicated as "(edited)" (#333)

UI changes: * 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.

40400.0.0

This release supports server version 4.4.

New features: The active color theme can be customized by creating a theme customization file and setting the new themeCustomizationFile 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 configuration option: 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 M-l keybinding. This feature can be turned off using by setting the showOlderEdits configuration option to False. New commands: The /remove-user command removes a user from a channel. The /group-msg command creates a new private group channel including several users. The /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 gist and its associated discussion. The width of the channel list (in columns) is now configurable with channelListWidth, which defaults to 20. The 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-n and C-p. (fixes #139) Quotation blocks now include visible characters in addition to indentation. 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)

Package changes: PRACTICES.md is now listed in extra-doc-files. Three scripts usable with the /sh command are now listed in extra-doc-files: cowsay runs the message text through the cowsay shell command and formats the output as a verbatim block. This command requires the 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 the 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.

40000.1.0

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.

Bug fixes: The /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 #306) Improve uniqueness comparisons for URL lists

40000.0.2

Bug fixes: * Attachments no longer appear in duplicate for edited messages.

Package changes: * CHANGELOG.md is now listed in extra-doc-files.

40000.0.1

Package changes: Upgraded mattermost-api to 40000.0.1. Upgraded mattermost-api-qc to 40000.0.1.

Bug fixes: Ignore emoji_added websocket events rather than crashing due to JSON decode failures (#296) channel_viewed websocket events from 4.0 servers lacking a channel_id value no longer cause a client crash (https://mattermost.atlassian.net/browse/PLT-7252) * mkrelease.sh: use correct bindist file extension (#295)

40000.0.0

This release supports server version 4.0.

Package changes: Upgraded mattermost-api to 40000.0.0. Upgraded mattermost-api-qc to 40000.0.0.

Bug fixes: Attempts to /focus your own DM channel no longer trigger a server error (fixes #294) Message edits now properly restore message reactions and attachments (fixes #292) 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 messages.

New features: 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, showBackgroundActivity, which 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 the interface. * 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.

Internal changes: * Added support for 4.0's channel_viewed and channel_updated websocket events.

31000.0.0

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.

30802.1.0

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.

30802.0.0

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).

30701.0.0

This release supports server version 3.7.1.

New features: 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. When the 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 unexpected output. Added a /members command to show current channel membership. Channel header changes from other users will now cause the channel topic string to update. Added a /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.

Internal changes: * Added preemption support for asynchronous work queue processing. doAsync(With) now both take an AsyncPriority.

30600.2.4

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.

30600.2.3

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)

30600.2.2

  • 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.

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.

30600.2.0

  • 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.

30600.1.0

  • Upgraded to mattermost-api 30600.1.0. This fixed /me and /shrug server-side command execution failures.

30600.0.0

Initial versioned release for server version 3.6.0.

comments powered byDisqus