# mmcli

Interact with Mattermost on the command line and in scripts

## Features
- Send, edit, delete messages and replies
- Get all messages (`mmcli cat`) or last messages (`mmcli tail -n 200`) in a channel
- Watch channels for new messages (`mmcli tail -f`)
- List channels, watch list of channels for changes (`mmcli ls -f`)
- Add and remove emoji reactions, get list of custom emoji on server
- Set custom status
- Outputs either team, channel and user *names* (default) or *IDs* (`--ids`)
- JSON or TSV output

## Usage
```
mmcli [-h] [-i] [--format {tsv,json}] [--server SERVER] action [subarguments..]

options:
  -h, --help            show this help message and exit
  -i, --ids             use IDs instead of names
  --format {tsv,json}   output format; only json has all fields; default: json
  --server SERVER       e.g.: mattermost.example.org; example.org/mattermost; envvar: MM_SERVER

actions:
    login               retrieve an access token
    cat                 list messages in channel
    tail                list newest messages in channel
    ls                  list channels
    send                send message(s)
    rm                  delete message(s)
    edit                edit message(s)
    addreaction         add emoji reaction to a message
    removereaction      remove emoji reaction from a message
    listcustomemoji     list all custom emoji on the server
    status              update user status
    customstatus        update custom user status (emoji and message)
    lastread            last read message in channel; will be null if all messages are read

For further help, use `mmcli <action> -h`.
```

You can request an access token with `mmcli login`, then provide it to future incantations of mmcli by setting the environment variable MM_ACCESSTOKEN.

Where a "URL name" is required, "id:" plus an ID can also be used instead. So these could both be valid:
- town-square
- id:123abc456def789ghi012jkl34

Hint: JSON output can be filtered with jq(1).

## Installation
With pip or pipx:

```
git clone https://git.zeus.gent/midgard/mmcli
pipx install ./mmcli
```

## Development
To create a virtualenv and install the dependencies in it:
```
tools/create_venv.sh
```

Activate the virtualenv with `source venv/bin/activate`. To make this easier, you could create
an [alias][] `alias venv='source venv/bin/activate'` in your shell.

[alias]: https://www.computerworld.com/article/2598087/how-to-use-aliases-in-linux-shell-commands.html

If you introduce dependencies, list them in `pyproject.toml` under `dependencies`, and run
`tools/update_requirements.sh`.