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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mattermost-cli
-Version: 0.0.3
+Version: 0.0.4
 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
@@ -39,17 +39,16 @@ uvx --from mattermost-cli mm --help
 
 # Or install globally
 pip install mattermost-cli
-mm --help
 ```
 
 ## Setup
 
 ```bash
 # Interactive login (password + MFA)
-mm login
+mm login --url https://chat.example.com
 
 # Or with a Personal Access Token
-mm login --token <your-pat>
+mm login --url https://chat.example.com --token <your-pat>
 
 # Verify
 mm whoami
@@ -58,23 +57,59 @@ mm whoami
 ## Usage
 
 ```bash
-# List channels
-mm channels
+# Get oriented (mentions + unread + active channels in one call)
+mm overview
 
-# Show unread messages
-mm unread
-
-# Read messages from a channel
+# Read messages
 mm messages general
 mm messages general --since 1h
-mm messages @username          # DM with a user
+mm messages general --threads       # thread index view
+mm messages @alice                  # DM with a user
 
-# Read a thread
-mm thread <post-id>
+# Threads
+mm thread <post-id>                 # root + last 9 replies
+mm thread <post-id> --limit 0      # full thread
 
-# Search
+# Search and mentions
 mm search "deployment issue"
-mm mentions
+mm mentions                         # @-mentions in last 24h
+
+# Download files by file ID
+mm download abc123def456ghi789jkl012
+mm download abc123... def456... --output downloads/
+
+# Channel info
+mm channel general                  # purpose, members, pinned count
+mm channels --since 6h              # recently active channels
+mm unread                           # channels with unread messages
+mm pinned general                   # pinned posts
+mm members general                  # who's in the channel
+
+# People
+mm user @alice                      # profile, status, timezone
+```
+
+## JSON Output
+
+All commands output JSON by default. Key fields:
+
+- **`thread_id`** on every post - pass to `mm thread`
+- **`ref`** on channel entries - pass to `mm messages`
+- **`files[].id`** on posts with attachments - pass to `mm download`
+- **`is_bot`** / **`bot_name`** - webhook/bot posts flagged automatically
+- **`root`** on reply-mentions - the original message being replied to
+- **`reactions`** - emoji counts like `{"+1": 3}`
+
+Webhook posts automatically extract alert content from Slack-format attachments.
+
+Add `--human` for readable markdown output instead.
+
+## Agent Skill
+
+Install as a coding agent skill:
+
+```bash
+npx skills add rhnvrm/mattermost-cli
 ```
 
 ## Options

mattermost_cli-0.0.4/README.md

@@ -0,0 +1,112 @@
+# mattermost-cli
+
+Mattermost CLI for humans and agents.
+
+## Install
+
+```bash
+# Run directly (no install)
+uvx --from mattermost-cli mm --help
+
+# Or install globally
+pip install mattermost-cli
+```
+
+## Setup
+
+```bash
+# Interactive login (password + MFA)
+mm login --url https://chat.example.com
+
+# Or with a Personal Access Token
+mm login --url https://chat.example.com --token <your-pat>
+
+# Verify
+mm whoami
+```
+
+## Usage
+
+```bash
+# Get oriented (mentions + unread + active channels in one call)
+mm overview
+
+# Read messages
+mm messages general
+mm messages general --since 1h
+mm messages general --threads       # thread index view
+mm messages @alice                  # DM with a user
+
+# Threads
+mm thread <post-id>                 # root + last 9 replies
+mm thread <post-id> --limit 0      # full thread
+
+# Search and mentions
+mm search "deployment issue"
+mm mentions                         # @-mentions in last 24h
+
+# Download files by file ID
+mm download abc123def456ghi789jkl012
+mm download abc123... def456... --output downloads/
+
+# Channel info
+mm channel general                  # purpose, members, pinned count
+mm channels --since 6h              # recently active channels
+mm unread                           # channels with unread messages
+mm pinned general                   # pinned posts
+mm members general                  # who's in the channel
+
+# People
+mm user @alice                      # profile, status, timezone
+```
+
+## JSON Output
+
+All commands output JSON by default. Key fields:
+
+- **`thread_id`** on every post - pass to `mm thread`
+- **`ref`** on channel entries - pass to `mm messages`
+- **`files[].id`** on posts with attachments - pass to `mm download`
+- **`is_bot`** / **`bot_name`** - webhook/bot posts flagged automatically
+- **`root`** on reply-mentions - the original message being replied to
+- **`reactions`** - emoji counts like `{"+1": 3}`
+
+Webhook posts automatically extract alert content from Slack-format attachments.
+
+Add `--human` for readable markdown output instead.
+
+## Agent Skill
+
+Install as a coding agent skill:
+
+```bash
+npx skills add rhnvrm/mattermost-cli
+```
+
+## Options
+
+```
+--human    Human-readable markdown output (default is JSON)
+--team     Filter to a specific team
+--debug    Enable debug output
+```
+
+## Auth
+
+Two methods supported:
+
+**Password + MFA** (primary): `mm login` prompts interactively. Session token
+is stored locally - password is never saved to disk. When the session expires,
+run `mm login` again.
+
+**Personal Access Token** (optional): `mm login --token <pat>`. Requires admin
+to enable PATs on the Mattermost server. Tokens don't expire.
+
+Credentials stored at `~/.config/mm/config.json` (token only, 600 permissions).
+
+Environment variables override config: `MATTERMOST_URL`, `MATTERMOST_TOKEN`,
+`MATTERMOST_TEAM`.
+
+## License
+
+MIT

{mattermost_cli-0.0.3 → mattermost_cli-0.0.4}/docs/01-guide/01-commands.md

@@ -7,75 +7,17 @@ description: Complete command reference
 
 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
+## mm overview
 
-Show current user info and validate that auth is working.
+Get oriented in one call. Returns mentions, unread channels, and recently active channels.
 
 ```bash
-mm whoami
+mm overview                   # Last 6 hours (default)
+mm overview --since 1d        # Last 24 hours
+mm overview --since 0         # No time filter
 ```
 
-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.
+This is the best starting point - it replaces separate calls to `mm mentions`, `mm unread`, and `mm channels --since`.
 
 ## mm messages
 
@@ -88,9 +30,12 @@ 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
+mm messages general --threads         # Thread index view
 ```
 
-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.
+The `--threads` flag groups messages by thread and shows root message + reply count + last reply. Useful for busy channels where flat messages are hard to follow.
+
+For group DMs, use the `ref` field from `mm overview` or `mm channels` since group DM display names aren't addressable.
 
 ## mm thread
 
@@ -105,7 +50,29 @@ 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.
+The post ID can be any post in the thread (root or reply). The CLI resolves it to the full thread automatically.
+
+## mm download
+
+Download one or more attached files by file ID.
+
+```bash
+mm download abc123def456ghi789jkl012
+mm download abc123... def456... --output downloads/
+```
+
+Use the `files[].id` field from `mm messages`, `mm thread`, `mm mentions`, `mm pinned`, or `mm search` JSON output.
+
+## mm mentions
+
+Show posts that @mention you. Reply-mentions include a `root` field with the original message being replied to.
+
+```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
+```
 
 ## mm search
 
@@ -121,6 +88,17 @@ 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 channel
+
+Show info about a single channel.
+
+```bash
+mm channel general
+mm channel @alice              # DM info
+```
+
+Returns purpose, header, member count, pinned post count, last post time, and creation date.
+
 ## mm channels
 
 List all channels you belong to.
@@ -130,11 +108,81 @@ 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
+mm channels --since 6h          # Channels with recent activity
 ```
 
 Each entry includes a `ref` field for use with `mm messages`.
 
+## mm unread
+
+Show channels with unread messages. Muted channels are hidden by default.
+
+```bash
+mm unread
+mm unread --include-muted
+```
+
+Returns channels sorted by mention count (descending), then unread count.
+
+## mm pinned
+
+Show pinned posts in a channel.
+
+```bash
+mm pinned general
+mm pinned general --limit 5
+```
+
+Pinned posts are the channel's institutional memory - decisions, links, and important context.
+
+## mm members
+
+List members of a channel with online status.
+
+```bash
+mm members general
+```
+
+Sorted by status (online first). Shows username, display name, position, and status.
+
+## mm user
+
+Show user profile and status.
+
+```bash
+mm user @alice
+mm user alice                  # @ prefix is optional
+```
+
+Returns name, position, email, status (online/away/offline/dnd), and timezone.
+
+## mm login
+
+Authenticate with your Mattermost server.
+
+```bash
+mm login --url https://chat.example.com                # Interactive: password + MFA
+mm login --url https://chat.example.com --token <pat>  # Personal Access Token
+```
+
+Password login prompts for username, password, and (if enabled) MFA token. The session token is stored - your password is never written to disk.
+
+## 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
+```
+
 ## Global options
 
 These go before the command name:

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

@@ -0,0 +1,235 @@
+---
+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, pinned)
+
+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",
+  "file_count": 1
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Post ID |
+| `thread_id` | string | Root post ID if reply, own ID if root. Pass to `mm thread`. |
+| `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 |
+| `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 `{"id": "...", "name": "...", "size": 12345, "mime_type": "..."}` |
+| `team` | Search and mentions output | Team display name |
+| `is_bot` | Webhook/bot posts | Always `true` when present |
+| `bot_name` | Webhook posts with a display name | The webhook's username (e.g. `"alertmatter"`) |
+| `reactions` | Posts with emoji reactions | Object mapping emoji names to counts: `{"+1": 3}` |
+| `root` | Reply-mentions in `mm mentions` | The original message: `{"author": "@bob", "message": "...", "created_at": "..."}` |
+
+### Bot detection
+
+Posts from webhooks and bots are automatically flagged:
+
+```json
+{
+  "author": "@webhook-user",
+  "is_bot": true,
+  "bot_name": "alertmatter",
+  "message": "FIRING: Host out of disk space..."
+}
+```
+
+When a webhook post has an empty `message` but includes Slack-format attachments (common for alert systems), the CLI extracts the alert text automatically. Without this, bot posts in alert channels would appear as empty messages.
+
+### Downloading files
+
+When a post includes attachments, each file entry includes a stable `id` you can pass to `mm download`.
+
+```json
+{
+  "id": "ixtrtzkhk7fs9cayrz44uq5bgy",
+  "file_count": 1,
+  "files": [
+    {
+      "id": "abc123def456ghi789jkl012",
+      "name": "incident-report.pdf",
+      "size": 48213,
+      "mime_type": "application/pdf",
+      "extension": "pdf"
+    }
+  ]
+}
+```
+
+`mm download` returns one record per saved file:
+
+```json
+[
+  {
+    "file_id": "abc123def456ghi789jkl012",
+    "name": "incident-report.pdf",
+    "size": 48213,
+    "mime_type": "application/pdf",
+    "saved_to": "downloads/incident-report.pdf"
+  }
+]
+```
+
+## Overview (overview command)
+
+```json
+{
+  "since": "6h",
+  "mentions": [...],
+  "unread": [...],
+  "active_channels": [...]
+}
+```
+
+| Section | Contents |
+|---------|----------|
+| `mentions` | Posts that @-mention you (same shape as mentions command, with `root` on replies) |
+| `unread` | Channels with unread messages: `{channel, ref, type, unread, last_post_at}` |
+| `active_channels` | Channels with recent posts: `{channel, ref, type, last_post_at}` |
+
+## Thread index (messages --threads)
+
+```json
+[
+  {
+    "thread_id": "4tcdn8818bym8cnmjnmej7hxiy",
+    "root_author": "@alice",
+    "root_message": "Pushed a new build with the following changes...",
+    "root_created_at": "2026-02-09T06:38:47Z",
+    "reply_count": 66,
+    "channel": "engineering",
+    "last_reply_author": "@bob",
+    "last_reply_message": "Deployed and verified",
+    "last_reply_at": "2026-03-05T07:44:45Z"
+  }
+]
+```
+
+## Channels (channels command)
+
+```json
+{
+  "id": "eqdx3n8zo3yqzyf46sobm14uwa",
+  "name": "engineering",
+  "ref": "engineering",
+  "type": "Public",
+  "team": "Engineering",
+  "purpose": "Engineering discussion",
+  "header": "On-call: @alice"
+}
+```
+
+## Channel info (channel command)
+
+```json
+{
+  "id": "zq9mowj6ojr8tftad1oyrbgmre",
+  "name": "engineering",
+  "type": "Public",
+  "purpose": "Engineering discussion",
+  "header": "On-call: @alice",
+  "last_post_at": "2026-03-05T07:44:45Z",
+  "created_at": "2023-08-08T04:12:05Z",
+  "pinned_count": 11,
+  "member_count": 61
+}
+```
+
+## 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"
+}
+```
+
+## User (user command)
+
+```json
+{
+  "user_id": "w1gabcy35tnt5m5wscocbgampo",
+  "username": "alice",
+  "display_name": "Alice Smith",
+  "email": "alice@example.com",
+  "position": "Staff Engineer",
+  "status": "online",
+  "timezone": "Asia/Kolkata"
+}
+```
+
+## Members (members command)
+
+```json
+{
+  "user_id": "w1gabcy35tnt5m5wscocbgampo",
+  "username": "alice",
+  "display_name": "Alice Smith",
+  "status": "online",
+  "position": "Staff Engineer"
+}
+```
+
+Sorted by status: online first, then away, dnd, offline.
+
+## The ref field
+
+The `ref` field appears in `overview`, `channels`, and `unread` output. It's the exact string to pass to `mm messages`:
+
+- For named channels: the channel name (e.g. `general`)
+- For DMs and group DMs: the channel ID (since display names like `"alice, bob"` aren't addressable)
+
+```bash
+# From overview 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`
+
+## Type labels
+
+| API | Label |
+|-----|-------|
+| `O` | Public |
+| `P` | Private |
+| `D` | DM |
+| `G` | Group DM |

{mattermost_cli-0.0.3 → mattermost_cli-0.0.4}/docs/01-guide/04-tips.md

@@ -25,21 +25,21 @@ Use `--since 0` to disable the time filter (all results).
 A quick way to catch up:
 
 ```bash
-# 1. What needs attention?
-mm mentions
+# 1. Get the full picture in one call
+mm overview --since 12h
 
-# 2. Check thread sizes before diving in
-#    (look at reply_count to decide if you need --limit)
+# 2. Read mentions (root context tells you what each is about)
+mm mentions --since 12h
 
 # 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
+# 4. Scan busy channels with thread view
+mm messages <ref> --threads --since 12h
 
-# 5. Read messages in busy channels
-mm messages <ref> --since today
+# 5. Dive into specific threads from the index
+mm messages <ref> --since 12h       # Or flat view for quiet channels
 ```
 
 ## Piping with jq