matrix-commander is a Matrix client for people who live in a terminal

The scope is deliberately the terminal and nothing else

matrix-commander is a simple command-line Matrix client for sending, receiving, creating rooms, inviting, verifying, and so much more, and the project is explicit about what it is not.

It exclusively offers a command-line interface. There is no GUI and there are no windows, except for pop-up windows in OS notification. The name is a word-play on matrix-command and command line, and the small application size is stated at only around 250K.

The capability list is broader than the framing suggests. It sends Matrix text messages as well as text, image, audio, video or other arbitrary files, and it listens to and receive Matrix messages, images, audio and video. It downloads media files, performs Matrix emoji verification, performs actions of rooms such as creating rooms and inviting to rooms, and lists rooms and room members.

On the message side the detail is in the formatting options. It can send notices, formatted messages, Markdown messages and code-formatted messages, it splits long messages before sending, and it can send emojis in messages via shorthand.

Underneath, it uses the matrix-nio SDK, and both matrix-nio and matrix-commander are written in Python 3. The project also uses nio-template, which is a scaffolding project for building a matrix-nio application, and it is on PyPI, installable via pip, with a Docker image and a Nix package as the other distribution routes.

It is also listed in the Matrix ecosystem as a made for Matrix project, which is the kind of listing that matters because it is maintained by the protocol's own community rather than by a company with a product to sell.

The use cases are the best documentation the project has

The section on what the program is for lists a set of scenarios that read like a user-submitted collection, and they are more informative than a feature list because they show what people actually do with it.

The scripting cases come first. A bot or part of a bot, automating sending via programs and scripts, and as an alerter to send all sorts of alerts. One user uses it as a GitLab CI automation tool to report build success or failure to their internal Matrix room. Another uses it as an admin or automation tool, for cases like creating 175 rooms for a company roll-out, querying some 9000 rooms for visibility data, or collecting profile data of 7000 enterprise or public users, with the observation that many admin jobs can be reduced to running a simple bash script or a simple Python program using matrix-commander.

The reminder and reporting cases follow. Sending yourself or others daily or weekly reminders via a cron job, and a surf report case where someone combines matrix-commander with a cron job to publish daily early morning surf reports to their Element app.

Then the jukebox, where a user with a large collection of mp3 files on their server sends themselves a random song. And the ticker, where people send themselves stock prices from public ticker APIs, usually a single curl command piped into matrix-commander.

The self-contained ones are the ones that show the client can be used as a building block rather than an application. A poor-man's Matrix client for people who love the terminal and are too lazy to start Element. A poor-man's importer or exporter for moving 39 holiday pictures or 57 wedding pictures in and out of Matrix. A poor man's blogger keeping an audience informed in a public room. A poor man's diary, writing to your own diary room or gratitude room.

The ghost case is the most interesting for automation. matrix-commander can be used in an ephemeral fashion, in a fire-and-forget style, where a single batch command logs in, creates a new device, sends a message, and then logs out and deletes the device. That is a pattern with real privacy value, since a credential that deletes itself leaves less behind.

Encryption, credentials and how the client stores them

The feature list covers the security-relevant items directly.

End-to-end encryption is supported, along with storage for end-to-end encryption, which is the part that matters: the client has to keep the device keys and the megolm sessions somewhere between runs, because regenerating them on every invocation would break the encryption of the history it is reading.

Credentials are stored as well, and there are two ways to authenticate. The client supports an access token instead of a password, and it supports SSO, Single Sign-On. The access token route is the one that matters for automation, because a password login in a script means handling a password, while a token can be read from an environment variable and never printed.

The dependency list shows the shape of the implementation. matrix-nio with the e2e extra at 0.14.1 or newer is the SDK, and around it sit aiohttp for the async HTTP, aiofiles at 0.6.0 or newer for async file handling, notify2 with pyxdg for the OS notifications that are the one place a window appears, Pillow and python_magic for image and file type handling, emoji and markdown for the message formatting features, and uuid and datetime for identifiers and timestamps.

The requirements file also carries a note about dbus-python being indirectly required by notify2 and not directly required by matrix-commander, which is the kind of detail that saves an hour when the notification feature fails to start on a bare Linux box. There is also an async-timeout entry with a reference to an issue, so the timeout behaviour is a deliberate part of the design rather than an accident.

The repository is GPL-3.0, the last push was on 2026-07-23, and there are no GitHub releases. The version lives in a VERSION file at the root, and there is a PyPI-Instructions.md for the publishing process.

Project structure and the help files that live in the repository

The repository tree has a few things worth pointing out, because they tell you what the maintainers prioritise.

There is a scripts/ directory, an auto-completion/ directory, a docker/ directory, an event-templates/ directory, and tests/. There are also three help files at the root: help.help.txt, help.manual.txt and help.usage.txt.

Those three files are the documentation, kept in the repository rather than only on a website, which means the help output is versioned with the code. It also means the usage text is a text file rather than generated from the argument parser, so it can be read in a diff, and it is a common pattern for CLI tools to ship a man-page-like file.

The auto-completion directory suggests shell completion for the commands, which is a small quality-of-life feature that a lot of CLI projects skip. The event-templates directory is for the messages the client can emit on events, and the docker directory is for the container image.

The packaging is old-fashioned in a way that is worth noticing. There is a setup.py that does almost nothing, since it imports setuptools and calls setup() inside an if __name__ guard, and the pyproject.toml contains only a build-system section requiring setuptools at 42 or newer with the setuptools.build_meta backend. There is no project metadata in pyproject.toml at all, which means the package metadata lives in setup.cfg, and there is a MANIFEST.in for the sdist file list. The requirements file is a plain list with no version pins beyond the two that need them.

The stack for a CLI client like this is deliberately minimal: setuptools, a requirements file, and a directory of modules. There is no build step, no Rust toolchain, no compiled extension.

Maintenance moved to a new maintainer in June 2026

The news section records a governance change, and it is the most current fact in the repository.

For the reason of transparency and the reason of appreciation, the announcement says that as of June 2026 there is a new maintainer on the project, Benjamin-Loison, who has full permissions including publishing new releases.

That last clause is the significant one. A project without release publishing rights is a project where the author has to do every release personally, and a project with them can ship while the author is unavailable. It is a common pattern for a long-running volunteer project to reach a point where the original maintainer wants company or family time back, and the handover is a reasonable way to keep the software alive.

The other news item is about the Rust rewrite. The project points at matrix-commander-rs, described as an incomplete matrix-commander but in Rust, and asks for stars and contributions. The word incomplete is doing real work in that sentence. A Rust client would remove the Python dependency and the asyncio footprint, and the matrix-nio SDK itself is Python, so a Rust implementation either talks to the homeserver HTTP API directly or wraps the Python code.

For a user, the practical reading is that the Python version is the one to deploy today and the Rust version is a project to watch rather than to plan around.

The badges show the distribution routes clearly: PyPI with the Python versions and download counts, Docker Hub with pull counts, a Nix package, and the Matrix ecosystem listing. The code style is black, and the SDK badge confirms matrix-nio is the base.

Where matrix-commander sits against Element and the rest of the client ecosystem

The honest comparison is with Element, the reference client, and with the other terminal clients in the Matrix ecosystem.

Against Element, the difference is not capability but shape. Element is a full application with a rich editor, notifications, calls, rooms management and a persistent session. matrix-commander has no windows at all beyond an OS notification popup, which means it starts instantly, keeps no interface state, and is driven by flags and arguments rather than by interaction.

That shape is exactly right for automation, and exactly wrong for anything that needs to read a message and decide what to send based on it interactively. The use case list is honest about this, because the most elaborate entry, the admin tool for querying 9000 rooms, is still a script rather than a workflow you drive by hand.

The other comparison is with a general-purpose chat CLI, and here matrix-commander is more specific than the generic options would be. It knows about rooms, invites, media, emoji verification and device verification, so a script that needs to send a file to a room does not have to implement the Matrix client-server API to do it.

The one thing a reader should not miss is the difference between this project and a hosted service. matrix-commander is a client, and it talks to a homeserver you choose. That means the operational question is not whether the tool works but whether you have a homeserver to point it at, whether you want to run one, and what your key backup and device verification story is. The tool gives you the client half of that problem and leaves the server half to you, which is the honest split for a project that started as a way to send a message from a shell.

Editorial conclusion

Adopt matrix-commander if you script against Matrix, run it from cron or CI, or simply want to send a message without opening a desktop client, since it covers the full set of client operations from a terminal and exposes them as plain commands. Skip it if you want a graphical experience or if you need a maintained, feature-complete implementation on the Rust side, because the matrix-commander-rs project is explicitly described as incomplete. Verify first that your homeserver and account are reachable through the matrix-nio SDK, that you understand where credentials and encryption storage are kept on disk, and that the Python 3 version in your environment matches the versions the PyPI package supports.

Frequently asked questions

Official sources

1. 8go/matrix-commander on GitHub
2. Issues
3. License: GPL-3.0
4. README