{"id":51133846,"url":"https://github.com/joho1968/mtxctl","last_synced_at":"2026-06-25T15:30:54.104Z","repository":{"id":365044910,"uuid":"1270052788","full_name":"joho1968/mtxctl","owner":"joho1968","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-15T15:24:41.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T17:17:09.624Z","etag":null,"topics":["admin","admin-tools","cli","cli-tools","matrix","matrix-synapse","php","php8","php84","synapse"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joho1968.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-15T10:40:08.000Z","updated_at":"2026-06-15T15:27:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/joho1968/mtxctl","commit_stats":null,"previous_names":["joho1968/mtxctl"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/joho1968/mtxctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joho1968%2Fmtxctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joho1968%2Fmtxctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joho1968%2Fmtxctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joho1968%2Fmtxctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joho1968","download_url":"https://codeload.github.com/joho1968/mtxctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joho1968%2Fmtxctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34781499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admin","admin-tools","cli","cli-tools","matrix","matrix-synapse","php","php8","php84","synapse"],"created_at":"2026-06-25T15:30:53.299Z","updated_at":"2026-06-25T15:30:54.096Z","avatar_url":"https://github.com/joho1968.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mtxctl\n\nCommand-line admin tool for Matrix/Synapse homeservers. Wraps the Synapse Admin API\nfor day-to-day user, room, media, and federation management.\n\nBuilt on [matrix-php](https://codeberg.org/joho1968/matrix-php) and [symfony/console](https://symfony.com/doc/current/console.html).\n\n## Requirements\n\n- PHP 8.4+\n- Synapse homeserver with the Admin API accessible\n- An admin user's access token (not an Application Service token)\n\n## Installation\n\n```bash\ngit clone https://codeberg.org/joho1968/matrix-php ../matrix-php\ngit clone https://codeberg.org/joho1968/mtxctl \u0026\u0026 cd mtxctl\nphp8.4 /path/to/composer install --no-dev\ncp config/config.example.php config/config.php\n# edit config/config.php\n```\n\n`matrix-php` must be a sibling directory (`../matrix-php`) — it is a path\ndependency and is not bundled in this repository.\n\nOr deploy to a target directory or tarball:\n\n```bash\nphp8.4 deploy/deploy.php --target=/opt/mtxctl\nphp8.4 deploy/deploy.php --tar=/tmp/mtxctl.tar.gz\n```\n\nA shell alias keeps invocations short:\n\n```bash\nalias mtxctl='php8.4 /opt/mtxctl/bin/mtxctl.php'\n```\n\n## Configuration\n\n`config/config.php` returns a plain PHP array:\n\n```php\nreturn [\n    'homeserver_url' =\u003e 'https://matrix.example.com',\n    'admin_token'    =\u003e 'syt_...',\n];\n```\n\nTo obtain an admin token:\n\n```bash\ncurl -s -XPOST 'https://matrix.example.com/_matrix/client/v3/login' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"type\":\"m.login.password\",\"user\":\"admin\",\"password\":\"...\"}' \\\n  | jq -r .access_token\n```\n\n## Commands\n\n```\nphp8.4 bin/mtxctl.php \u003ccommand\u003e \u003caction\u003e [options]\n```\n\nAll commands accept `--json` for raw JSON output. Destructive actions require `--confirm`;\nrunning without it shows a dry-run preview.\n\n### user\n\n```bash\nuser list [--limit=N] [--from=N] [--deactivated] [--guests]\nuser show \u003c@user:server\u003e\nuser whois \u003c@user:server\u003e              # active sessions, IPs, devices\nuser deactivate \u003c@user:server\u003e [--erase] [--confirm]\nuser password \u003c@user:server\u003e \u003cnewpass\u003e\nuser admin \u003c@user:server\u003e             # grant admin\nuser admin --revoke \u003c@user:server\u003e    # revoke admin\nuser shadow-ban \u003c@user:server\u003e        # hide messages from everyone else\nuser shadow-ban --revoke \u003c@user:server\u003e\n```\n\n### room\n\nRoom identifiers accept a room ID (`!abc:server`) or an alias (`#alias:server`).\nBoth must be quoted in most shells — `#` is a comment and `!` triggers history\nexpansion, so the shell strips them before the argument reaches mtxctl.\n\n```bash\nroom list [--limit=N] [--from=N] [--search=term] [--retention]\nroom show \u003croom\u003e\nroom members \u003croom\u003e\nroom make-admin \u003croom\u003e --user \u003c@user:server\u003e     # works even if user is not a member\nroom kick \u003croom\u003e --user \u003c@user:server\u003e [--reason=\"...\"] [--confirm]\nroom power \u003croom\u003e --user \u003c@user:server\u003e          # show current power level\nroom power \u003croom\u003e --user \u003c@user:server\u003e --level N  # set power level (0=member, 50=mod, 100=admin)\nroom retention \u003croom\u003e                            # show retention for one room\nroom retention \u003croom\u003e --days=N [--confirm]       # set retention on one room\nroom retention \u003croom\u003e --clear [--confirm]        # clear retention on one room\nroom retention --search=term                     # show retention for all matching rooms\nroom retention --search=term --days=N [--confirm]  # bulk set (auto-promotes if needed)\nroom retention --search=term --clear [--confirm]   # bulk clear\nroom tombstone \u003cold-room\u003e \u003cnew-room\u003e [--body=\"...\"] [--confirm]\nroom delete \u003croom\u003e [--no-purge] [--confirm]\n```\n\n### media\n\n```bash\nmedia purge [--days=90] [--confirm]   # purge cached remote media older than N days\n```\n\nOnly cached copies of media fetched from other homeservers are removed.\nLocally uploaded files and protected media are never touched.\n\n### token\n\n```bash\ntoken list\ntoken show \u003ctoken\u003e\ntoken create [--token=\u003cstr\u003e] [--uses=N] [--expires-days=N]\ntoken delete \u003ctoken\u003e [--confirm]\n```\n\n### federation\n\n```bash\nfederation list [--limit=N] [--from=N]\nfederation show \u003cserver\u003e\n```\n\n### server\n\n```bash\nserver version   # Synapse and Python version\nserver stats     # user count, room count, version\n```\n\n### version\n\n```bash\nversion          # mtxctl version, license, and copyright\n```\n\n## License\n\nGNU Affero General Public License v3.0 or later. See `LICENSE`.\n\nSee [matrix-php](../matrix-php/) for the underlying library.\n \n## Copyright\n\nWritten by Joaquim Homrighausen while converting caffeine into code.\nCopyright 2026 Joaquim Homrighausen; all rights reserved.\n\nSponsored by WebbPlatsen i Sverige AB, Sweden.\n\nIf you need a GDPR-safe place to host your Matrix, Mattermost, and/or\nRocketChat instance, get in touch with support@webbplatsen.se\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoho1968%2Fmtxctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoho1968%2Fmtxctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoho1968%2Fmtxctl/lists"}