Quickstart

Install

# Run directly (no install needed)
uvx --from mattermost-cli mm --help

# Or install globally
pip install mattermost-cli

The package name is mattermost-cli, the CLI command is mm. With uvx, use --from since the names differ.

Authenticate

Password + MFA (most common):

mm login

You'll be prompted for your server URL, username, password, and MFA token. The session token is stored locally -- your password is never saved to disk.

Personal Access Token (if your server allows it):

mm login --token your-pat-here

You'll be prompted for the server URL. The token is stored and used for all future requests.

Verify it works:

mm whoami

{
  "user_id": "w1gab...",
  "username": "alice",
  "display_name": "Alice Chen",
  "email": "alice@example.com",
  "teams": [
    {"id": "kofs...", "name": "engineering", "display_name": "Engineering"}
  ]
}

First commands

Check what's unread:

mm unread

This returns all channels with unread messages, sorted by mention count. Each entry includes a ref field -- use it to read messages from that channel.

See who's mentioning you:

mm mentions

Returns @mentions from the last 24 hours. Each mention includes thread_id so you can fetch the full conversation.

Read a thread:

mm thread abc123def456ghi789jkl012

Returns the root message + last 9 replies by default. Use --limit 0 for the full thread, or --since 1h for recent replies only.

Download an attachment:

mm messages incidents --limit 5     # inspect files[].id in JSON output
mm download abc123def456ghi789jkl012 --output downloads/

Human-readable output:

mm --human mentions

## #engineering

**@bob** (06:52) [2 replies, files: screenshot.png]
@alice can you review this deployment config?

## #incidents

**@carol** (04:17)
Reminder to check the monitoring dashboard. @alice @dave

Configuration

Credentials are stored at ~/.config/mm/config.json with 0600 permissions. Only the session token and server URL are saved.

Environment variables override the config file:

Next steps

• Commands -- Full reference for all commands
• JSON Output -- Understand the output format
• Tips -- Filtering, searching, and workflow patterns