mattermost-cli 0.0.1__tar.gz

mattermost_cli-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mattermost_cli-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.tox/
+.pytest_cache/
+_version.py

mattermost_cli-0.0.1/AGENTS.md

@@ -0,0 +1,97 @@
+# Agent Instructions
+
+Instructions for AI agents working on this repository.
+
+## Overview
+
+mattermost-cli is a Mattermost CLI for humans and agents. JSON output by default for agent consumption, `--human` flag for markdown. Published to PyPI as `mattermost-cli`, CLI command is `mm`.
+
+## Architecture
+
+```
+mmchat/
+  cli.py         # Click commands - all 8 commands, State object, argument resolution
+  client.py      # Driver wrapper - URL parsing, auth, MMContext, Team dataclass
+  config.py      # Token storage at ~/.config/mm/config.json (0600 perms)
+  resolve.py     # User/channel ID resolution with in-memory caching (Resolver class)
+  formatters.py  # JSON (default) and markdown output formatting
+  time_utils.py  # --since argument parsing (relative, named, absolute, raw epoch)
+tests/
+  test_time_utils.py  # Pure function tests
+  test_config.py      # File I/O with tmp_path fixtures
+  test_client.py      # URL parsing, formatter output shapes
+```
+
+## Key design decisions
+
+**Read-only**: No write operations to Mattermost. The `_resolve_channel` function scans existing channels for DMs instead of using `create_direct_message_channel` (which is a write op).
+
+**JSON-first output**: Default output is JSON for agent consumption. `--human` flag switches to markdown tables. All formatters have both `format_*_json` and `format_*_md` variants.
+
+**Agent-tuned defaults**: Commands are tuned for an agent running them bare (no flags), then using `--help` to refine:
+- `mm thread` defaults to `--limit 10` (root + last 9 replies), not full thread
+- `mm mentions` defaults to `--since 1d`, not all time
+- `mm messages` defaults to `--limit 30`
+
+**Cross-team by default**: All data commands iterate all user teams and deduplicate results. `--team` narrows to one.
+
+**No passwords on disk**: Only session tokens are stored. Password+MFA login creates a session token and stores that. Config file has 0600 permissions, directory 0700.
+
+## Dependencies
+
+- `mattermostdriver` (7.3.2) - wraps Mattermost REST API v4. The driver takes separate scheme/host/port options, NOT a full URL. `client.py:create_driver()` handles URL parsing.
+- `click` (8.0+) - CLI framework
+- `httpx` - HTTP client (used by mattermostdriver internally, also imported for ConnectError handling)
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+Tests cover pure logic only (config, time parsing, URL parsing, formatters). API-dependent commands are tested manually against a live instance.
+
+When adding tests: use `tmp_path` and `monkeypatch` for isolation. Don't mock the driver - test pure functions that don't need it.
+
+## Common patterns
+
+**Adding a new CLI command**: 
+1. Add the function in `cli.py` with `@main.command()` and `@pass_state`
+2. Use `get_context(state)` to get authenticated `MMContext`
+3. Create `Resolver(ctx.driver, ctx.user_id)` if you need name resolution
+4. Output with `format_*_json` / `format_*_md` based on `state.human`
+
+**JSON output fields for posts**: Every post includes `thread_id` (root_id if reply, own id if root), `is_reply`, `reply_count` (on root posts only), `created_at` (ISO 8601), `file_count`, and `files` (with name/size when available). These fields exist specifically for agent triage workflows.
+
+**The `ref` field**: `mm unread` and `mm channels` JSON output includes a `ref` field - the exact string to pass to `mm messages <ref>`. For named channels this is the channel name (e.g. `gtt`), for DMs/group DMs it's the channel_id (since their display names like "karan, rhnvrm, shravan.bk" aren't addressable). Always use `ref`, never `channel` or `channel_id` directly.
+
+**Resolver caching**: `Resolver` caches user and channel lookups per session. Use `resolve_users()` for batch resolution (one API call for all uncached IDs). Call `format_channel()` (public method) for channel info - not `_resolve_dm_name` directly.
+
+## Gotchas
+
+- The mattermostdriver logs passwords when `debug=True`. `create_driver()` always sets `debug=False`.
+- DM channel names are `{uid1}__{uid2}` (double underscore). Group DMs are hashes.
+- `get_channels_for_user` returns raw API channel dicts. The `type` field is a single letter: O/P/D/G. Formatters map these to "Public"/"Private"/"DM"/"Group DM".
+- Thread API returns posts newest-first. Must sort by `create_at` for chronological display.
+- The `--since` filter on `mm thread` keeps the root post regardless of age (for context), then filters replies by time.
+- `reply_count` comes from the Mattermost API post object - only present on root posts that have replies.
+- File metadata (`name`, `size`) is in `post["metadata"]["files"]` - only present when the API returns it (depends on post age and server config).
+- `mm mentions` uses Mattermost search API with `@username after:YYYY-MM-DD` syntax. The `--since 0` disables the date filter.
+
+## Publishing
+
+```bash
+# Build
+python -m build
+
+# Upload to PyPI
+twine upload dist/*
+
+# Users install with
+uvx mmchat
+# or
+pip install mmchat
+```
+
+The PyPI package name is `mattermost-cli`. The CLI command is `mm`.

mattermost_cli-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mattermost_cli-0.0.1/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: mattermost-cli
+Version: 0.0.1
+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
+Project-URL: Issues, https://github.com/rhnvrm/mattermost-cli/issues
+Author-email: Rohan Verma <hello@rohanverma.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: httpx<1.0.0,>=0.20.0
+Requires-Dist: mattermostdriver>=7.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mattermost-cli
+
+Mattermost CLI for humans and agents.
+
+## Install
+
+```bash
+# via uvx (recommended)
+uvx mattermost-cli --help
+
+# or pip
+pip install mattermost-cli
+```
+
+## Setup
+
+```bash
+# Interactive login (password + MFA)
+mm login
+
+# Or with a Personal Access Token
+mm login --token <your-pat>
+
+# Verify
+mm whoami
+```
+
+## Usage
+
+```bash
+# List channels
+mm channels
+
+# Show unread messages
+mm unread
+
+# Read messages from a channel
+mm messages general
+mm messages general --since 1h
+mm messages @username          # DM with a user
+
+# Read a thread
+mm thread <post-id>
+
+# Search
+mm search "deployment issue"
+mm mentions
+```
+
+## 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.1/README.md

@@ -0,0 +1,76 @@
+# mattermost-cli
+
+Mattermost CLI for humans and agents.
+
+## Install
+
+```bash
+# via uvx (recommended)
+uvx mattermost-cli --help
+
+# or pip
+pip install mattermost-cli
+```
+
+## Setup
+
+```bash
+# Interactive login (password + MFA)
+mm login
+
+# Or with a Personal Access Token
+mm login --token <your-pat>
+
+# Verify
+mm whoami
+```
+
+## Usage
+
+```bash
+# List channels
+mm channels
+
+# Show unread messages
+mm unread
+
+# Read messages from a channel
+mm messages general
+mm messages general --since 1h
+mm messages @username          # DM with a user
+
+# Read a thread
+mm thread <post-id>
+
+# Search
+mm search "deployment issue"
+mm mentions
+```
+
+## 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.1/mmchat/__init__.py

@@ -0,0 +1,6 @@
+"""mattermost-cli - Mattermost CLI for humans and agents."""
+
+try:
+    from mmchat._version import __version__
+except ImportError:
+    __version__ = "0.0.0-dev"

mattermost_cli-0.0.1/mmchat/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None