mm-pipe is a command-line tool designed to facilitate seamless interactions with a Mattermost instance. It enables users to send messages, share files, and perform various operations directly from the terminal.
- Send Messages: Pipe text directly to specific users or channels.
- File Sharing: Upload and share files effortlessly.
- Syntax Highlighting: Applys syntax highlighting to code snippets.
- Binary File Detection: Upload binary files as attachment.
- Message Length Automation: Upload content as file attachment if it passes specified length limit.
- Flexible Configuration: Supports multiple methods for setting server URL and API token.
- User and Channel Listing: Retrieve and display lists of users and channels.
- Instance Selection: Access different configurations using the
--instanceparameter.
To install mm-pipe, clone the repository, install the required dependencies, and the package too
git clone https://github.com/ysf/mm-pipe.git
cd mm-pipe
pip install .add this if you want to debug/fix/add a feature to allow tests to work:
pip install ".[dev]"If you have a working python setup, after the installation, mm-pipe should be available in your cli. I suggest creating a config file with your personal token and using the autocompletion features for bash/zsh and fzf next.
mm-pipe requires the server URL and an API token to connect to your Mattermost instance.
To use mm-pipe, you'll need a personal access token from your Mattermost account:
-
Enable Personal Access Tokens:
- As a System Admin, navigate to System Console > Integrations > Integration Management.
- Ensure that Enable Personal Access Tokens is set to
true.
-
Generate a Token:
- Log in to your Mattermost account.
- Go to Account Settings > Security > Personal Access Tokens.
- Click Create Token, provide a description, and save it.
- Copy the generated token and store it securely; you won't be able to view it again.
For detailed instructions, refer to the Mattermost Personal Access Tokens documentation.
Now that you have a token, mm-pipe can be configured in several ways:
Create a default configuration file at ~/.mm-pipe.conf:
[default]
server_url=https://mattermost.default.com
token=<yourtokenhere>
# tokencmd=secret-tool lookup mattermost token
auto_highlight=True
max_message_length=4000Replace https://mattermost.default.com with your Mattermost server URL and <yourtokenhere> with your personal access token.
Using tokencmd for Secure Token Storage
You can use the tokencmd option (inspired by Matterhorn) to retrieve your token from a password manager / secure storage:
[default]
server_url=https://mattermost.default.com
tokencmd=secret-tool lookup mattermost tokenWhen mm-pipe runs, it will execute the command specified in tokencmd and use its output as the token. This keeps your token out of plain text configuration files.
Token retrieval priority is:
- Command line argument (--token)
- Configuration file token
- tokencmd output
- Environment variable (MM_TOKEN)
Using Multiple Instances:
To manage multiple configurations, define them under different sections in the configuration file:
[default]
server_url=https://mattermost.default.com
token=<defaulttoken>
[work]
server_url=https://mattermost.work.com
token=<worktoken>
[friends]
server_url=https://mattermost.friends.com
token=<personaltoken>You can specify which instance to use with the --instance parameter:
echo "Your message" | mm-pipe --instance work --user usernameUsing a Custom Configuration File:
If you prefer to use a different location for the configuration file, specify its path with the --config parameter:
mm-pipe --config /path/to/your/config.confSet the following environment variables:
export MM_PIPE_SERVER_URL=https://mattermost.yoururl.com
export MM_PIPE_TOKEN=<yourtokenhere>Provide the server URL and token directly when running mm-pipe:
echo "Your message" | mm-pipe --server https://mattermost.yoururl.com --token <yourtokenhere> --user usernameHere are some common use cases for mm-pipe:
mm-pipe --user username --message "hey there."
# or
echo "Hello, this is a test message." | mm-pipe --user usernameecho "System maintenance will occur at midnight." | mm-pipe --channel channelnamemm-pipe --user username --file /path/to/yourfile.txtecho "System maintenance will occur at midnight." | mm-pipe --channel channelname -m "## IMPORTANT"cat script.py | mm-pipe --channel devs --highlight pythonTo see if your mm-pipe setup works, you can list the users/channels on your provided default instance. This feature is used for the autocompletion on --user or fzf-completion via CTRL+N, but might still be useful for a different workflow.
mm-pipe --list-users
# or
mm-pipe --list-channels--help: Shows commandline help.--server-url: Mattermost server URL.--token: Personal access token.--instance: Specify the configuration instance to use.--config: Path to a custom configuration file.--user: Specify the recipient username.--channel: Specify the target channel.--file: Path to the file to send.--message: Directly specify a message.--highlight: Apply syntax highlighting (e.g.,auto,python,javascript).--max-message-length: Maximum message length before posting message as attachment (default: 4000).--list-users: Display a list of all users.--list-channels: Display a list of all channels.--bash: Output bash completion to source withsource <(mm-pipe --bash)--zsh: Output zsh completion to source withsource <(mm-pipe --zsh)
mm-pipe supports autocompletion for zsh shells.
After installing mm-pipe, add the following to your ~/.bashrc:
export MM_PIPE_USE_FZF=1
# export MM_PIPE_KEYBIND="\\C-n" # CTRL+N is default
source <(mm-pipe --bash)Add the following to your ~/.zshrc:
export MM_PIPE_USE_FZF=1
# export MM_PIPE_KEYBIND="^N" # CTRL+N is default
source <(mm-pipe --zsh)If you're regurlarly copy and pasting something to a specific Mattermost target. Using an alias might help:
# you put this to your aliases
alias devs="mm-pipe --instance work --channel devs -m"
alias bestfriend="mm-pipe --instance friends --user bestfriend -m"
# and later in your shell, will
$ ps aux | grep http | devs
$ bestfriend "time for lunch?"The tabcompletion on --instance will show the instances found in your ~/.mm-pipe.conf file. On --user and --channel it will show/complete valid users and channels. The fzf completion on CTRL+N will add | mm-pipe --user username to the current commandline. This allows sending command outputs directly to mattermost. If the commandline is empty, hence no command has been entered yet, CTRL+N assumes you want to send a message and mm-pipe --user username -m "" will be entered into the prompt, with the cursor waiting between the quotes for your message.
This project is licensed under the MIT License.