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.

• 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 (with inviter, type, timestamp) and accept individually
• Auto-join — optionally accept all pending room invitations on startup (--auto-join)
• Device management — list registered devices, 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)
• Structured logging via loguru

pip install minimatrix

git clone https://github.com/vroomfondel/minimatrix.git
cd minimatrix
make install
source .venv/bin/activate

docker build -t minimatrix .

# ~/.config/minimatrix/config.yaml
homeserver: "https://matrix.example.com"
user: "myuser"
password: "mypassword"

minimatrix rooms

# List pending invites
minimatrix invites
minimatrix invites list

# Accept a specific invite
minimatrix invites accept --room '!abc123:example.com'

minimatrix send --room '!abc123:example.com' "Hello from minimatrix!"

# Or pipe from stdin
echo "Hello from a pipe" | minimatrix send --room '!abc123:example.com'

# Send a single file
minimatrix send --room '!abc123:example.com' --file /path/to/image.png

# Send multiple files
minimatrix send --room '!abc123:example.com' -f photo.jpg -f document.pdf

# Send a file with a text message
minimatrix send --room '!abc123:example.com' --file photo.jpg "Check this out!"

Files are automatically uploaded with the correct MIME type (m.image, m.audio, m.video, or m.file) and encrypted for E2E rooms. Image dimensions are included in metadata when Pillow is installed.

minimatrix listen --room '!abc123:example.com'
# [2026-02-22 14:30:01] <@alice:example.com> Hi there!
# Press Ctrl+C to stop

# List all registered devices
minimatrix devices
minimatrix devices list

# Import E2E keys from old crypto store DBs
minimatrix devices import-keys
minimatrix devices import-keys --delete-old-stores

# Purge all devices except the current one
minimatrix devices purge

Configuration is resolved in this order (later overrides earlier):

1. YAML config file (~/.config/minimatrix/config.yaml by default)
2. Environment variables
3. CLI arguments

Use minimatrix --help or minimatrix <subcommand> --help for full usage.

When AUTH_METHOD=jwt is set, minimatrix authenticates via Keycloak ROPC (Resource Owner Password Credentials) grant instead of direct Matrix password login. This enables centralized identity management through Keycloak while allowing non-interactive authentication.

sequenceDiagram
    participant CLI as minimatrix
    participant KC as Keycloak
    participant Syn as Synapse

    CLI->>KC: 1. ROPC grant (username + password)
    KC-->>CLI: 2. JWT access token
    CLI->>Syn: 3. Matrix login (JWT)
    Syn->>KC: 4. Validate JWT (JWKS or introspection)
    KC-->>Syn: JWT valid
    Syn-->>CLI: 5. Matrix access token

Requires synapse-token-authenticator on the Synapse side for the com.famedly.login.token.* login types.

• Keycloak instance (any recent version)
• Synapse homeserver
• Admin access to both Keycloak and Synapse

Create a dedicated realm for Matrix (or use an existing one).

Recommended realm settings:

• registrationAllowed: false — disable self-registration
• loginWithEmailAllowed: false — use usernames, not emails (Matrix localparts)
• registrationEmailAsUsername: false — important for Matrix username compatibility

Create a confidential client with ROPC (Direct Access Grants) enabled:

After creation, copy the Client secret from the Credentials tab.

Create a user account in your Keycloak realm. The Keycloak username must match the desired Matrix localpart — Synapse extracts it from the preferred_username JWT claim.

modules:
  - module: synapse_token_authenticator.TokenAuthenticator
    config:
      oauth:
        jwt_validation:
          jwks_endpoint: "https://keycloak.example.com/realms/<realm>/protocol/openid-connect/certs"
          localpart_path: "preferred_username"
          require_expiry: true
          validator:
            type: exist
        registration_enabled: true

modules:
  - module: synapse_token_authenticator.TokenAuthenticator
    config:
      jwt:
        secret: "your-256-bit-secret-here"
        algorithm: HS512
        allow_registration: false
        require_expiry: true

# Get the realm public key
curl -s "https://keycloak.example.com/realms/<realm>" | jq -r '.public_key'

jwt_config:
  enabled: true
  secret: |
    -----BEGIN PUBLIC KEY-----
    <paste the public key here>
    -----END PUBLIC KEY-----
  algorithm: "RS256"
  subject_claim: "preferred_username"
  issuer: "https://keycloak.example.com/realms/<realm>"

"Invalid username or password" from Synapse:

• Verify the Keycloak user exists and password is correct
• Check that preferred_username in JWT matches an existing Matrix user (or registration_enabled: true)
• Verify JWKS endpoint is accessible from Synapse

"ROPC grant failed" from Keycloak:

• Ensure directAccessGrantsEnabled: true on the client
• Verify client secret is correct
• Check user is enabled in Keycloak

"JWT signature validation failed":

• For JWKS: verify the endpoint URL is correct and accessible
• For native JWT: ensure public key is correctly formatted with PEM headers
• Check issuer matches the JWT iss claim

Tests are pure unit tests (no Matrix server or network access required) and can be run freely with make tests. Pre-commit hooks (.pre-commit-config.yaml) include gitleaks for secret scanning — be careful not to commit Matrix credentials or tokens.

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.

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

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

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.