https://github.com/joho1968/mtxctl
Command-line admin tool for Matrix/Synapse homeservers written for PHP 8.4+. Wraps the Synapse Admin API for day-to-day user, room, media, and federation management.
https://github.com/joho1968/mtxctl
admin admin-tools cli cli-tools matrix matrix-synapse php php8 php84 synapse
Last synced: 4 days ago
JSON representation
Command-line admin tool for Matrix/Synapse homeservers written for PHP 8.4+. Wraps the Synapse Admin API for day-to-day user, room, media, and federation management.
- Host: GitHub
- URL: https://github.com/joho1968/mtxctl
- Owner: joho1968
- License: agpl-3.0
- Created: 2026-06-15T10:40:08.000Z (14 days ago)
- Default Branch: main
- Last Pushed: 2026-06-15T15:24:41.000Z (14 days ago)
- Last Synced: 2026-06-15T17:17:09.624Z (14 days ago)
- Topics: admin, admin-tools, cli, cli-tools, matrix, matrix-synapse, php, php8, php84, synapse
- Language: PHP
- Homepage:
- Size: 39.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# mtxctl
Command-line admin tool for Matrix/Synapse homeservers. Wraps the Synapse Admin API
for day-to-day user, room, media, and federation management.
Built on [matrix-php](https://codeberg.org/joho1968/matrix-php) and [symfony/console](https://symfony.com/doc/current/console.html).
## Requirements
- PHP 8.4+
- Synapse homeserver with the Admin API accessible
- An admin user's access token (not an Application Service token)
## Installation
```bash
git clone https://codeberg.org/joho1968/matrix-php ../matrix-php
git clone https://codeberg.org/joho1968/mtxctl && cd mtxctl
php8.4 /path/to/composer install --no-dev
cp config/config.example.php config/config.php
# edit config/config.php
```
`matrix-php` must be a sibling directory (`../matrix-php`) — it is a path
dependency and is not bundled in this repository.
Or deploy to a target directory or tarball:
```bash
php8.4 deploy/deploy.php --target=/opt/mtxctl
php8.4 deploy/deploy.php --tar=/tmp/mtxctl.tar.gz
```
A shell alias keeps invocations short:
```bash
alias mtxctl='php8.4 /opt/mtxctl/bin/mtxctl.php'
```
## Configuration
`config/config.php` returns a plain PHP array:
```php
return [
'homeserver_url' => 'https://matrix.example.com',
'admin_token' => 'syt_...',
];
```
To obtain an admin token:
```bash
curl -s -XPOST 'https://matrix.example.com/_matrix/client/v3/login' \
-H 'Content-Type: application/json' \
-d '{"type":"m.login.password","user":"admin","password":"..."}' \
| jq -r .access_token
```
## Commands
```
php8.4 bin/mtxctl.php [options]
```
All commands accept `--json` for raw JSON output. Destructive actions require `--confirm`;
running without it shows a dry-run preview.
### user
```bash
user list [--limit=N] [--from=N] [--deactivated] [--guests]
user show <@user:server>
user whois <@user:server> # active sessions, IPs, devices
user deactivate <@user:server> [--erase] [--confirm]
user password <@user:server>
user admin <@user:server> # grant admin
user admin --revoke <@user:server> # revoke admin
user shadow-ban <@user:server> # hide messages from everyone else
user shadow-ban --revoke <@user:server>
```
### room
Room identifiers accept a room ID (`!abc:server`) or an alias (`#alias:server`).
Both must be quoted in most shells — `#` is a comment and `!` triggers history
expansion, so the shell strips them before the argument reaches mtxctl.
```bash
room list [--limit=N] [--from=N] [--search=term] [--retention]
room show
room members
room make-admin --user <@user:server> # works even if user is not a member
room kick --user <@user:server> [--reason="..."] [--confirm]
room power --user <@user:server> # show current power level
room power --user <@user:server> --level N # set power level (0=member, 50=mod, 100=admin)
room retention # show retention for one room
room retention --days=N [--confirm] # set retention on one room
room retention --clear [--confirm] # clear retention on one room
room retention --search=term # show retention for all matching rooms
room retention --search=term --days=N [--confirm] # bulk set (auto-promotes if needed)
room retention --search=term --clear [--confirm] # bulk clear
room tombstone [--body="..."] [--confirm]
room delete [--no-purge] [--confirm]
```
### media
```bash
media purge [--days=90] [--confirm] # purge cached remote media older than N days
```
Only cached copies of media fetched from other homeservers are removed.
Locally uploaded files and protected media are never touched.
### token
```bash
token list
token show
token create [--token=] [--uses=N] [--expires-days=N]
token delete [--confirm]
```
### federation
```bash
federation list [--limit=N] [--from=N]
federation show
```
### server
```bash
server version # Synapse and Python version
server stats # user count, room count, version
```
### version
```bash
version # mtxctl version, license, and copyright
```
## License
GNU Affero General Public License v3.0 or later. See `LICENSE`.
See [matrix-php](../matrix-php/) for the underlying library.
## Copyright
Written by Joaquim Homrighausen while converting caffeine into code.
Copyright 2026 Joaquim Homrighausen; all rights reserved.
Sponsored by WebbPlatsen i Sverige AB, Sweden.
If you need a GDPR-safe place to host your Matrix, Mattermost, and/or
RocketChat instance, get in touch with support@webbplatsen.se