xomoxcc/minimatrix repository overview

⁠minimatrix

Standalone Matrix CLI client with E2E encryption. Send messages, listen to rooms, manage invitations, manage devices, and list joined rooms — all from the command line.

• Source: GitHub⁠
• PyPI: minimatrix⁠
• License: LGPLv3

⁠Features

• Send encrypted messages to Matrix rooms
• Send files — upload and send images, documents, audio, and video with automatic MIME type detection and E2E encryption
• Listen for incoming messages in real-time (prints to stdout)
• List joined rooms with display names and member counts
• Manage invites — list pending invitations and accept individually or auto-join on startup
• Device management — list, purge orphaned devices, and import E2E keys from old crypto stores
• Session caching — persists Matrix access tokens to avoid re-authentication on every run
• E2E encryption via matrix-nio with persistent crypto store and device reuse
• TOFU device trust — automatically trusts all devices in a room
• Multiple auth methods: password, SSO, or JWT via Keycloak (ROPC + JWKS)
• Flexible config: YAML file, environment variables, and CLI args (in ascending priority)

⁠Quick Start

docker run --rm xomoxcc/minimatrix:latest

⁠Usage Examples

# List joined rooms and pending invites
minimatrix --user myuser --password mypass --homeserver https://matrix.example.com rooms

# List and accept invitations
minimatrix --user myuser --password mypass invites
minimatrix --user myuser --password mypass invites accept --room '!abc:example.com'

# Send a message
minimatrix --user myuser --password mypass send --room '!abc:example.com' "Hello!"

# Send a file (or multiple with repeated -f)
minimatrix --user myuser --password mypass send --room '!abc:example.com' --file /path/to/image.png
minimatrix --user myuser --password mypass send --room '!abc:example.com' -f photo.jpg -f doc.pdf "Check these!"

# Listen for messages
minimatrix --user myuser --password mypass listen --room '!abc:example.com'

# Manage devices
minimatrix --user myuser --password mypass devices
minimatrix --user myuser --password mypass devices purge
minimatrix --user myuser --password mypass devices import-keys --delete-old-stores

Or use a config file at ~/.config/minimatrix/config.yaml:

homeserver: "https://matrix.example.com"
user: "myuser"
password: "mypassword"

⁠Configuration

⁠JWT Authentication (Keycloak)

Set AUTH_METHOD=jwt to authenticate via Keycloak ROPC grant instead of direct Matrix password login.

Requires synapse-token-authenticator⁠ on the Synapse side. See the README⁠ for a full setup guide.

⁠Image Details

• Base: python:3.14-slim-trixie
• Non-root user (pythonuser)
• Entrypoint: tini --
• Multi-arch: linux/amd64, linux/arm64

⁠Building the Image

# Simple local build
docker build -t minimatrix .

# Multi-arch build & push (via GitHub Actions or local script)
./repo_scripts/build-container-multiarch.sh

⁠License

This project is licensed under the LGPL where applicable/possible — see LICENSE.md⁠. Some files/parts may use other licenses: MIT⁠ | GPL⁠ | LGPL⁠. Always check per‑file headers/comments.

⁠Authors

• Repo owner (primary author)
• Additional attributions are noted inline in code comments

⁠Acknowledgments

• Inspirations and snippets are referenced in code comments where appropriate.

⁠⚠️ Note

This is a development/experimental project. For production use, review security settings, customize configurations, and test thoroughly in your environment. 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. Use at your own risk.