<commit_before>
# Authentication

`matterhorn` supports username/password authentication as well as
authentication by Personal Access Token or session token. The following
subsections provide details on using each method.

## Username / Password Authentication

Matterhorn's start-up login user interface will allow you to provide
a username and password for authentication. We recommend that you
put the username in your Matterhorn configuration file and configure
Matterhorn to obtain your password from your system keychain. See the
`docs/sample-config.ini` file for documentation on the `user` and
`passcmd` settings, respectively.

## Personal Access Token Authentication

Matterhorn's start-up login user interface will also allow you to
provide an session or Personal Access Token. If a token is provided, it
will take precedence over a username and password.

We recommend Personal Access Tokens because they don't expire except
when revoked. To use a Personal Access Token:

* Ask your Mattermost server administrator to enable Personal Access
  Tokens on your Mattermost account.
* Create a Personal Access Token.
* Add the new token to your system keychain. (Details on how to do this
  depend on your platform.)
* Configure Matterhorn's `tokencmd` configuration option to query the
  system keychain to get the token. See `docs/sample-config.ini` for
  examples of how to do this with `passcmd` and `tokencmd`.

The steps for configuring Personal Access Tokens can be found in [the
Mattermost documentation](https://docs.mattermost.com/developer/personal-access-tokens.html).

## Token Cookie Authentication

If your server does not support username and password authentication
(e.g. if GitLab authentication is the only supported method), you can
use your browser client's token cookie to authenticate:

* Authenticate to GitLab (or other identity provider) using the
  Mattermost web client.
* Once your browser has returned to the Mattermost interace, obtain the
  value of the `MMAUTHTOKEN` browser cookie.
* Start Matterhorn and enter the value of the `MMAUTHTOKEN` token in the
  login interface field labeled `Access token:` or add the token to the
  system keychain as described above.

Please note that unlike a Personal Access Token, the web client's token
cookie will expire, so these steps will need to be repeated each time
you log in with Matterhorn. As a result, we strongly recommend the use
of a Personal Access Token instead if at all possible.

Firefox users: you might consider using the
[mattermost-session-cookie-firefox](https://github.com/ftilde/mattermost-session-cookie-firefox)
script to make this process easier.

# 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
`docs/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. Keybinding and command help may be obtained in a number of ways:

* The `/help` command within Matterhorn.
* The `F1` key within Matterhorn.
* Running matterhorn with the `-k` or `-m` arguments to get a text table of available keybindings or commands respectively.
* Running matterhorn with the `-k` or `-m` arguments with `-f markdown` to get a [Markdown table of available keybindings](docs/keybindings.md) or [Markdown table of available commands](docs/commands.md).

    Note: The keyboard and command output commands do not start the
    client but simply print to stdout and exit. The keybindings shown
    include any user overrides from the config files; use the `-i`
    flag to skip loading the local config files and see the Matterhorn
    default keybindings.

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

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.<commit_msg>Fix broken UserGuide links<commit_after>
# Authentication

`matterhorn` supports username/password authentication as well as
authentication by Personal Access Token or session token. The following
subsections provide details on using each method.

## Username / Password Authentication

Matterhorn's start-up login user interface will allow you to provide
a username and password for authentication. We recommend that you
put the username in your Matterhorn configuration file and configure
Matterhorn to obtain your password from your system keychain. See the
`docs/sample-config.ini` file for documentation on the `user` and
`passcmd` settings, respectively.

## Personal Access Token Authentication

Matterhorn's start-up login user interface will also allow you to
provide an session or Personal Access Token. If a token is provided, it
will take precedence over a username and password.

We recommend Personal Access Tokens because they don't expire except
when revoked. To use a Personal Access Token:

* Ask your Mattermost server administrator to enable Personal Access
  Tokens on your Mattermost account.
* Create a Personal Access Token.
* Add the new token to your system keychain. (Details on how to do this
  depend on your platform.)
* Configure Matterhorn's `tokencmd` configuration option to query the
  system keychain to get the token. See `docs/sample-config.ini` for
  examples of how to do this with `passcmd` and `tokencmd`.

The steps for configuring Personal Access Tokens can be found in [the
Mattermost documentation](https://docs.mattermost.com/developer/personal-access-tokens.html).

## Token Cookie Authentication

If your server does not support username and password authentication
(e.g. if GitLab authentication is the only supported method), you can
use your browser client's token cookie to authenticate:

* Authenticate to GitLab (or other identity provider) using the
  Mattermost web client.
* Once your browser has returned to the Mattermost interace, obtain the
  value of the `MMAUTHTOKEN` browser cookie.
* Start Matterhorn and enter the value of the `MMAUTHTOKEN` token in the
  login interface field labeled `Access token:` or add the token to the
  system keychain as described above.

Please note that unlike a Personal Access Token, the web client's token
cookie will expire, so these steps will need to be repeated each time
you log in with Matterhorn. As a result, we strongly recommend the use
of a Personal Access Token instead if at all possible.

Firefox users: you might consider using the
[mattermost-session-cookie-firefox](https://github.com/ftilde/mattermost-session-cookie-firefox)
script to make this process easier.

# 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
`docs/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. Keybinding and command help may be obtained in a number of ways:

* The `/help` command within Matterhorn.
* The `F1` key within Matterhorn.
* Running matterhorn with the `-k` or `-m` arguments to get a text table of available keybindings or commands respectively.
* Running matterhorn with the `-k` or `-m` arguments with `-f markdown` to get a [Markdown table of available keybindings](keybindings.md) or [Markdown table of available commands](commands.md).

    Note: The keyboard and command output commands do not start the
    client but simply print to stdout and exit. The keybindings shown
    include any user overrides from the config files; use the `-i`
    flag to skip loading the local config files and see the Matterhorn
    default keybindings.

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

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.
{'fraction_non_alphanumeric': 0.05495185087021822, 'fraction_numerical': 0.0007067762169802986, 'mean_word_length': 4.468599033816425, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1255922', 'n_tokens_mistral': 2913, 'n_tokens_neox': 2813, 'n_words': 1642}