mattercli

Scriptable Mattermost CLI for bot and personal access token operations. Zero required dependencies.

No comparable tool exists — mmctl is admin-only, Matterhorn is a TUI. Nothing does scriptable bot/PAT operations from the command line. This fills that gap.

Install

npm install -g mattercli

Requires Node.js >= 18.

Quick Start

# Interactive setup — saves to ~/.mattercli/config.json
mattercli init

# Or use environment variables
export MATTERCLI_URL=https://mattermost.example.com
export MATTERCLI_TOKEN=your-bot-or-pat-token

# Verify
mattercli whoami

Commands

Messaging

mattercli post <channel> <message>       # Post to a channel
mattercli dm <user> <message>            # Direct message
mattercli recent <channel> [count]       # Read recent posts
mattercli search <terms>                 # Full-text search (--or for OR)
mattercli thread <post-id>               # View a thread
mattercli thread <post-id> <reply>       # Reply to a thread
mattercli mentions                       # Show your @mentions

Channels & Users

mattercli channels                       # List joined channels
mattercli users search <term>            # Find users
mattercli users info <username>          # User details

Reactions & Files

mattercli react <post-id> <emoji>        # Add reaction
mattercli react <post-id> <emoji> --remove  # Remove reaction
mattercli upload <channel> <file> [msg]  # Upload file attachment

Status & Webhooks

mattercli status                         # Show your status
mattercli status away                    # Set status (online|away|dnd|offline)
mattercli webhook send <url> <text>      # Fire incoming webhook
mattercli webhook list                   # List webhooks
mattercli webhook create <channel>       # Create webhook

Live Streaming

# Requires: npm install ws
mattercli watch                          # Stream all messages
mattercli watch <channel>                # Stream one channel

Utilities

mattercli alias set k knowledge          # Create channel shorthand
mattercli alias list                     # List aliases
mattercli alias rm k                     # Remove alias
mattercli completions [bash|zsh|fish]    # Shell tab completions

Configuration

Multi-Server Profiles

mattercli init  # Run multiple times for different servers

Config lives at ~/.mattercli/config.json (chmod 600):

{
  "version": 1,
  "default": "work",
  "servers": {
    "work": {
      "url": "https://mattermost.example.com",
      "token": "...",
      "teamName": "MyTeam"
    }
  },
  "aliases": { "k": "knowledge" }
}

Resolution Order

Credentials resolve in this order:

1. CLI flags (--url, --token)
2. Environment variables (MATTERCLI_URL, MATTERCLI_TOKEN)
3. Config file server profile (--server <name> or default)
4. Legacy .env fallback (MATTERMOST_URL, MATTERMOST_BOT_TOKEN)

Global Flags

--server <name>     # Use a specific server profile
--team <name>       # Override team selection
--json              # Output as JSON (all commands)
--help              # Show help
--version           # Show version

JSON Mode

Every command supports --json for scripting:

# Pipe to jq
mattercli channels --json | jq '.[].name'

# Use in scripts
POST_ID=$(mattercli post general "deploy started" --json | jq -r '.id')
mattercli react "$POST_ID" rocket

Shell Completions

# Bash — add to ~/.bashrc
eval "$(mattercli completions bash)"

# Zsh — add to ~/.zshrc
eval "$(mattercli completions zsh)"

# Fish
mattercli completions fish | source

Binary Aliases

Both mattercli and mm are available after install:

mm whoami
mm post general "hello"

Dependencies

• Required: None. Uses Node.js builtins and native fetch.
• Optional: ws — only needed for mattercli watch (WebSocket streaming).

License

MIT — Abeedoo Labs