mattermost-cli 0.0.2__tar.gz → 0.0.3__tar.gz

mattermost_cli-0.0.3/.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  docs:
+    uses: oddship/moat/.github/workflows/build-docs.yml@main
+    with:
+      docs_dir: docs

{mattermost_cli-0.0.2 → mattermost_cli-0.0.3}/.gitignore

@@ -10,4 +10,3 @@ build/
 venv/
 .tox/
 .pytest_cache/
-_version.py

{mattermost_cli-0.0.2 → mattermost_cli-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mattermost-cli
-Version: 0.0.2
+Version: 0.0.3
 Summary: Mattermost CLI for humans and agents
 Project-URL: Homepage, https://github.com/rhnvrm/mattermost-cli
 Project-URL: Repository, https://github.com/rhnvrm/mattermost-cli
@@ -34,11 +34,12 @@ Mattermost CLI for humans and agents.
 ## Install
 
 ```bash
-# via uvx (recommended)
-uvx mattermost-cli --help
+# Run directly (no install)
+uvx --from mattermost-cli mm --help
 
-# or pip
+# Or install globally
 pip install mattermost-cli
+mm --help
 ```
 
 ## Setup

{mattermost_cli-0.0.2 → mattermost_cli-0.0.3}/README.md

@@ -5,11 +5,12 @@ Mattermost CLI for humans and agents.
 ## Install
 
 ```bash
-# via uvx (recommended)
-uvx mattermost-cli --help
+# Run directly (no install)
+uvx --from mattermost-cli mm --help
 
-# or pip
+# Or install globally
 pip install mattermost-cli
+mm --help
 ```
 
 ## Setup

mattermost_cli-0.0.3/docs/01-guide/01-commands.md

@@ -0,0 +1,147 @@
+---
+title: Commands
+description: Complete command reference
+---
+
+# Commands
+
+All commands output JSON by default. Add `--human` before any command for markdown output. Add `--team <name>` to filter to a specific team.
+
+## mm login
+
+Authenticate with your Mattermost server.
+
+```bash
+mm login                    # Interactive: password + MFA
+mm login --token <pat>      # Personal Access Token
+```
+
+Password login prompts for server URL, username, password, and (if enabled) MFA token. The session token is stored -- your password is never written to disk.
+
+When the session expires, run `mm login` again.
+
+## mm logout
+
+Revoke the current session and clear stored credentials.
+
+```bash
+mm logout
+```
+
+## mm whoami
+
+Show current user info and validate that auth is working.
+
+```bash
+mm whoami
+```
+
+Returns your user ID, username, display name, email, and list of teams.
+
+## mm unread
+
+Show channels with unread messages.
+
+```bash
+mm unread
+mm unread --team Engineering
+```
+
+Returns channels sorted by mention count (descending), then unread count.
+
+Each entry includes:
+
+| Field | Description |
+|-------|-------------|
+| `channel_id` | Internal channel ID |
+| `channel` | Display name |
+| `ref` | Use this with `mm messages <ref>` |
+| `type` | Public, Private, DM, or Group DM |
+| `unread` | Number of unread messages |
+| `mentions` | Number of @mentions |
+| `team` | Team name |
+| `last_post_at` | Timestamp of last post |
+
+The `ref` field is important: for named channels it's the channel name (e.g. `general`), for DMs and group DMs it's the channel ID (since their display names aren't addressable). Always use `ref` when passing a channel to other commands.
+
+## mm mentions
+
+Show posts that @mention you.
+
+```bash
+mm mentions                   # Last 24 hours (default)
+mm mentions --since 2h        # Last 2 hours
+mm mentions --since 0         # All time
+mm mentions --limit 10        # Max 10 results
+```
+
+Results are grouped by channel in `--human` mode.
+
+## mm messages
+
+Read messages from a channel.
+
+```bash
+mm messages general                   # By channel name
+mm messages @alice                    # DM with a user
+mm messages abc123def456...           # By channel ID (for group DMs)
+mm messages general --limit 10        # Last 10 messages
+mm messages general --since 2h        # Messages from last 2 hours
+mm messages general --since today     # Messages from today
+```
+
+For group DMs, use the `ref` field from `mm unread` or `mm channels` since group DM display names (e.g. "alice, bob, carol") aren't addressable.
+
+## mm thread
+
+Read a thread by any post ID in that thread.
+
+```bash
+mm thread abc123def456...             # Root + last 9 replies (default)
+mm thread abc123def456... --limit 0   # Full thread
+mm thread abc123def456... --limit 5   # Root + last 4 replies
+mm thread abc123def456... --since 1h  # Root + replies from last hour
+```
+
+The root message is always included regardless of `--limit` or `--since` so you have context.
+
+The post ID can be any post in the thread -- root or reply. The CLI resolves it to the full thread automatically.
+
+## mm search
+
+Search messages across all teams.
+
+```bash
+mm search "deployment issue"
+mm search "deployment issue" --limit 10
+mm search "from:alice"                        # Mattermost search modifiers
+mm search "in:engineering deployment"         # Search in a specific channel
+mm search "before:2026-03-01 incident"        # Date filters
+```
+
+Supports all [Mattermost search modifiers](https://docs.mattermost.com/collaborate/search-for-messages.html): `from:`, `in:`, `before:`, `after:`, `on:`, etc.
+
+## mm channels
+
+List all channels you belong to.
+
+```bash
+mm channels                     # All channels
+mm channels --type public       # Only public channels
+mm channels --type dm           # Only DMs
+mm channels --type group        # Only group DMs
+mm channels --type private      # Only private channels
+```
+
+Each entry includes a `ref` field for use with `mm messages`.
+
+## Global options
+
+These go before the command name:
+
+```bash
+mm --human mentions             # Markdown output
+mm --team Engineering unread    # Filter to one team
+mm --debug messages general     # Debug logging
+mm --version                    # Show version
+```

mattermost_cli-0.0.3/docs/01-guide/02-json-output.md

@@ -0,0 +1,135 @@
+---
+title: JSON Output
+description: Output format reference for programmatic use
+---
+
+# JSON Output
+
+All commands output JSON by default. This page documents the shape of each output.
+
+## Posts (messages, mentions, thread, search)
+
+Every post has these fields:
+
+```json
+{
+  "id": "ixtrtzkhk7fs9cayrz44uq5bgy",
+  "thread_id": "ixtrtzkhk7fs9cayrz44uq5bgy",
+  "is_reply": false,
+  "author": "@alice",
+  "message": "Can you check the deployment config?",
+  "created_at": "2026-03-05T06:52:30Z",
+  "channel": "engineering",
+  "channel_id": "eqdx3n8zo3yqzyf46sobm14uwa",
+  "team": "Engineering",
+  "file_count": 1
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Post ID |
+| `thread_id` | string | Root post ID if this is a reply, own ID if this is a root post |
+| `is_reply` | boolean | Whether this post is a reply in a thread |
+| `author` | string | @username of the author |
+| `message` | string | Post text content |
+| `created_at` | string | ISO 8601 timestamp (UTC) |
+| `channel` | string | Channel display name |
+| `channel_id` | string | Channel ID |
+| `team` | string | Team display name |
+| `file_count` | integer | Number of file attachments |
+
+### Conditional fields
+
+These appear only when relevant:
+
+| Field | When | Description |
+|-------|------|-------------|
+| `reply_count` | Root posts with replies | Number of replies in the thread |
+| `files` | Posts with file metadata | Array of `{"name": "...", "size": 12345}` |
+
+The `reply_count` field is useful for deciding whether to fetch a thread. A thread with 3 replies is worth fetching in full; one with 141 replies should use `--limit`.
+
+## Channels (channels command)
+
+```json
+{
+  "id": "eqdx3n8zo3yqzyf46sobm14uwa",
+  "name": "engineering",
+  "ref": "engineering",
+  "type": "Public",
+  "team": "Engineering",
+  "purpose": "Engineering discussion",
+  "header": "On-call: @alice"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Channel ID |
+| `name` | string | Display name |
+| `ref` | string | Argument to pass to `mm messages` |
+| `type` | string | `Public`, `Private`, `DM`, or `Group DM` |
+| `team` | string | Team display name |
+| `purpose` | string | Channel purpose (if set) |
+| `header` | string | Channel header (if set) |
+
+## Unread (unread command)
+
+```json
+{
+  "channel_id": "km4f6k31ibbpteg9875fpxb5gw",
+  "channel": "alice, bob, carol",
+  "ref": "km4f6k31ibbpteg9875fpxb5gw",
+  "type": "Group DM",
+  "unread": 5,
+  "mentions": 3,
+  "team": "Engineering",
+  "last_post_at": "2026-03-05T06:52:30Z"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `channel_id` | string | Channel ID |
+| `channel` | string | Display name |
+| `ref` | string | Argument to pass to `mm messages` |
+| `type` | string | `Public`, `Private`, `DM`, or `Group DM` |
+| `unread` | integer | Unread message count |
+| `mentions` | integer | @mention count |
+| `team` | string | Team display name |
+| `last_post_at` | string | ISO 8601 timestamp of last post |
+
+## The ref field
+
+The `ref` field appears in both `channels` and `unread` output. It's the exact string to pass to `mm messages`:
+
+- For named channels: the channel name (e.g. `general`, `gtt`)
+- For DMs: the channel ID (since DM "names" like `alice, bob, carol` aren't addressable)
+
+```bash
+# From unread output: {"channel": "alice, bob", "ref": "km4f6k31ibb..."}
+mm messages km4f6k31ibb...    # Works (using ref)
+mm messages "alice, bob"       # Fails (display name not addressable)
+```
+
+## Timestamps
+
+All timestamps are ISO 8601 in UTC:
+
+```
+2026-03-05T06:52:30Z
+```
+
+The Mattermost API returns epoch milliseconds internally. The CLI converts these for readability.
+
+## Type labels
+
+Channel types from the API are single letters (`O`, `P`, `D`, `G`). The CLI maps them to readable labels:
+
+| API | Label |
+|-----|-------|
+| `O` | Public |
+| `P` | Private |
+| `D` | DM |
+| `G` | Group DM |

mattermost_cli-0.0.3/docs/01-guide/03-authentication.md

@@ -0,0 +1,99 @@
+---
+title: Authentication
+description: Login methods and token storage
+---
+
+# Authentication
+
+## Methods
+
+### Password + MFA
+
+The most common method. Works with SSO servers that accept password login.
+
+```bash
+mm login
+```
+
+Prompts for:
+1. **Server URL** -- e.g. `https://chat.example.com`
+2. **Username** -- your Mattermost username
+3. **Password** -- your password
+4. **MFA token** -- if MFA is enabled on your account
+
+On success, a session token is created and stored locally. Your password is never written to disk.
+
+Session tokens expire based on server configuration (typically 30 days of inactivity). When it expires, run `mm login` again.
+
+### Personal Access Token
+
+If your Mattermost admin has enabled personal access tokens:
+
+```bash
+mm login --token mmtok_abc123...
+```
+
+Prompts for the server URL only. The token is stored and used directly.
+
+PATs don't expire unless revoked, making them better for automated use.
+
+## Token storage
+
+Credentials are stored at:
+
+```
+~/.config/mm/config.json
+```
+
+The directory is created with 0700 permissions, the file with 0600.
+
+Contents:
+
+```json
+{
+  "url": "https://chat.example.com",
+  "auth_method": "password",
+  "token": "session-token-here"
+}
+```
+
+Only the session token is stored. For PAT auth, `auth_method` is `"token"`.
+
+## Environment variables
+
+Environment variables override the config file. Useful for CI, containers, or agent environments.
+
+| Variable | Description |
+|----------|-------------|
+| `MATTERMOST_URL` | Server URL (overrides config) |
+| `MATTERMOST_TOKEN` | Auth token (overrides config) |
+| `MATTERMOST_TEAM` | Filter to one team (like `--team`) |
+| `MM_CONFIG_PATH` | Custom config file path |
+
+Example:
+
+```bash
+export MATTERMOST_URL=https://chat.example.com
+export MATTERMOST_TOKEN=mmtok_abc123...
+mm whoami
+```
+
+## Verify authentication
+
+```bash
+mm whoami
+```
+
+If auth is valid, returns your user info and teams. If the token has expired:
+
+```
+Error: Session expired. Run 'mm login' to re-authenticate.
+```
+
+## Logout
+
+Revoke the session and clear stored credentials:
+
+```bash
+mm logout
+```

mattermost_cli-0.0.3/docs/01-guide/04-tips.md

@@ -0,0 +1,135 @@
+---
+title: Tips
+description: Practical patterns for daily use
+---
+
+# Tips
+
+## The --since flag
+
+Most commands accept `--since` for time-based filtering. Supported formats:
+
+```bash
+mm mentions --since 30m        # Last 30 minutes
+mm mentions --since 2h         # Last 2 hours
+mm mentions --since 1d         # Last 24 hours (default for mentions)
+mm messages general --since 3d # Last 3 days
+mm messages general --since today   # Since midnight
+mm thread abc... --since 1h         # Root + replies from last hour
+```
+
+Use `--since 0` to disable the time filter (all results).
+
+## Morning triage workflow
+
+A quick way to catch up:
+
+```bash
+# 1. What needs attention?
+mm mentions
+
+# 2. Check thread sizes before diving in
+#    (look at reply_count to decide if you need --limit)
+
+# 3. Read threads that matter
+mm thread <thread_id>
+mm thread <thread_id> --limit 5    # Big thread? Just the recent end
+
+# 4. Scan unread channels
+mm unread
+
+# 5. Read messages in busy channels
+mm messages <ref> --since today
+```
+
+## Piping with jq
+
+Since output is JSON, you can use `jq` to filter and transform:
+
+```bash
+# Channels with mentions
+mm unread | jq '[.[] | select(.mentions > 0)]'
+
+# Just channel names and mention counts
+mm unread | jq '.[] | {channel, mentions}' 
+
+# Messages from a specific author
+mm messages general | jq '[.[] | select(.author == "@alice")]'
+
+# Thread IDs from mentions for batch processing
+mm mentions | jq -r '.[].thread_id' | sort -u
+
+# Posts with attachments
+mm messages general | jq '[.[] | select(.file_count > 0)]'
+```
+
+## Searching effectively
+
+Mattermost search supports modifiers:
+
+```bash
+mm search "from:alice deployment"           # Posts by alice about deployment
+mm search "in:engineering before:2026-03-01" # Channel + date filter
+mm search "from:alice from:bob"             # Posts from alice OR bob
+mm search '"exact phrase"'                  # Exact match (quote inside quotes)
+```
+
+See the [Mattermost search documentation](https://docs.mattermost.com/collaborate/search-for-messages.html) for the full modifier list.
+
+## Working with DMs
+
+Direct messages use `@username`:
+
+```bash
+mm messages @alice              # 1:1 DM
+mm messages @alice --limit 5    # Last 5 messages
+```
+
+Group DMs can't be addressed by name. Use the `ref` field from `mm unread` or `mm channels`:
+
+```bash
+# Find the group DM
+mm unread | jq '.[] | select(.type == "Group DM")'
+
+# Use the ref field
+mm messages km4f6k31ibb...
+```
+
+## Thread navigation
+
+Every post has a `thread_id`. For root posts, it equals the post `id`. For replies, it points to the root.
+
+```bash
+# Get mentions
+mm mentions
+# Output: {"thread_id": "abc123...", "is_reply": true, ...}
+
+# Fetch that thread
+mm thread abc123...
+# Output: root post + replies, chronologically
+
+# Big thread? Check reply_count first, then limit
+mm thread abc123... --limit 5
+```
+
+## Human-readable output
+
+The `--human` flag outputs markdown instead of JSON:
+
+```bash
+mm --human mentions
+mm --human thread abc123...
+mm --human messages general --since today
+```
+
+Human output includes annotations like `[12 replies, files: report.pdf]` on posts that have them.
+
+## Cross-team by default
+
+All commands search across all your teams and deduplicate results. Use `--team` to narrow:
+
+```bash
+mm unread --team Engineering
+mm search "deployment" --team Engineering
+mm channels --team Engineering
+```

mattermost_cli-0.0.3/docs/config.toml

@@ -0,0 +1,14 @@
+site_name = "mattermost-cli"
+base_path = "/mattermost-cli"
+
+[highlight]
+light = "github"
+dark  = "github-dark"
+
+[[links]]
+title = "GitHub"
+url = "https://github.com/rhnvrm/mattermost-cli"
+
+[[links]]
+title = "PyPI"
+url = "https://pypi.org/project/mattermost-cli/"

mattermost_cli-0.0.3/docs/index.md

@@ -0,0 +1,72 @@
+---
+title: mattermost-cli
+description: Mattermost CLI for humans and agents
+---
+
+# mattermost-cli
+
+A CLI for Mattermost that outputs JSON by default, designed for both human use and agent automation. Runs against any Mattermost server with personal access tokens or password+MFA auth.
+
+## Install
+
+```bash
+# Run directly (no install)
+uvx --from mattermost-cli mm --help
+
+# Or install globally
+pip install mattermost-cli
+mm --help
+```
+
+## What it does
+
+```bash
+mm login                          # Authenticate (password+MFA or token)
+mm unread                         # Channels with unread messages
+mm mentions                       # Posts that @mention you (last 24h)
+mm messages general               # Read channel messages
+mm messages @knadh                # Read DMs with a user
+mm thread abc123def456...         # Read a thread by post ID
+mm search "deployment issue"      # Search across all teams
+mm channels                       # List all your channels
+```
+
+Every command outputs JSON by default. Add `--human` for markdown.
+
+## JSON-first
+
+Default output is structured JSON with fields designed for programmatic consumption:
+
+```json
+{
+  "id": "abc123...",
+  "thread_id": "def456...",
+  "is_reply": true,
+  "author": "@alice",
+  "message": "Can you check this?",
+  "created_at": "2026-03-05T06:52:30Z",
+  "channel": "engineering",
+  "reply_count": 12,
+  "file_count": 1,
+  "files": [{"name": "screenshot.png", "size": 66657}]
+}
+```
+
+ISO 8601 timestamps, human-readable type labels, thread IDs on every post, file metadata included.
+
+## Agent-tuned defaults
+
+Commands are tuned for running without flags first, then refining with `--help`:
+
+- `mm mentions` defaults to last 24 hours (not all time)
+- `mm thread` returns root + last 9 replies (not the entire thread)
+- `mm unread` includes a `ref` field you can pass directly to `mm messages`
+
+## Learn more
+
+- [Quickstart](quickstart/) -- Install, authenticate, first commands
+- **Guide**
+  - [Commands](guide/commands/) -- All commands with examples
+  - [JSON Output](guide/json-output/) -- Output format reference
+  - [Authentication](guide/authentication/) -- Login methods and token storage
+  - [Tips](guide/tips/) -- Filtering, searching, and workflow patterns