matrix-administration

# Matrix Administration Stdlib-only Python wrappers around the Synapse [Admin API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html) and the Client-Server API. Reads `~/.config/matrix/config.json` (the same file matrix-communication uses). ## Quick Reference ```bash S=skills/matrix-administration/scripts python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-fetch-rooms.py [--server :example.com] python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-rate-rooms.py --space '!home:srv' [--language de] python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-graph.py --space '!home:srv' python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-biggest-rooms.py [-n 10] python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-join-room.py '!room:srv' '@user:srv' python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-make-admin.py '!room:srv' '@user:srv' python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-add-to-space.py '!room:srv' '!space:srv' python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-migrate-room.py '!room:srv' '@admin:srv' '!space:srv' # DESTRUCTIVE, asks first python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-deactivate-user.py '@user:srv' # DESTRUCTIVE python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-user-rooms.py '@user:srv' python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-user-admin-rooms.py '@user:srv' python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-room-member-flow.py '!room:srv' python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-search.py '!room:srv' '@bot:srv' deploy ``` ## Scripts | Script | Purpose | |--------|---------| | `synapse-fetch-rooms.py` | Snapshot all rooms + state → `rooms.json` | | `synapse-rate-rooms.py` | Health checks (EN/DE) on `rooms.json` | | `synapse-graph.py` | Render `rooms.json` → Graphviz `.dot` + `.svg` | | `synapse-biggest-rooms.py` | Top-N rooms by DB size | | `synapse-join-room.py` | Force-join a user | | `synapse-make-admin.py` | Promote to PL 100 | | `synapse-add-to-space.py` | Send `m.space.child` | | `synapse-migrate-room.py` | Add to space + restrict + encrypt | | `synapse-deactivate-user.py` | **Destructive** deactivation (`--erase` for GDPR) | | `synapse-user-admin-rooms.py` | Local: rooms where user is PL 100 | | `synapse-user-rooms.py` | Local: rooms a user belongs to | | `synapse-room-member-flow.py` | Join/leave timeline | | `synapse-search.py` | Unencrypted history search | ## Setup `~/.config/matrix/config.json` (respects `$XDG_CONFIG_HOME`): ```json { "homeserver": "https://matrix.example.com", "admin_token": "syt_admin_…", "room_filter": ":example.com", "default_space_id": "!home:example.com", "home_space_ids": ["!home:example.com"] } ``` `homeserver` and either `admin_token` or `access_token` (server-admin) are required. The other fields are optional. To keep the token out of this file, set `admin_token_file` to a file holding it (relative paths resolve against the config directory) or export `MATRIX_ADMIN_TOKEN`; the environment wins over the file, the file over the inline value. Env fallbacks: `MATRIX_USER_ID`, `MATRIX_SPACE_ID`, `LANGUAGE=en|de`, `NO_COLOR`. ## Safety The token is server-admin. Read [`references/safety-guide.md`](references/safety-guide.md) before any destructive op. - `synapse-deactivate-user.py` is irreversible. - `synapse-migrate-room.py` enables encryption (one-way) and restricts joins; it prints the plan and asks before the first write (`--yes` skips, and is required without a terminal). Power-level changes restored on exit including Ctrl-C. - `synapse-make-admin.py` raises PL 100 permanently. - `synapse-search.py` cannot read E2EE — empty ≠ no messages. - `rooms.json` exposes user IDs; never commit it. ## References - [`references/synapse-admin-api.md`](references/synapse-admin-api.md) — endpoints + upstream docs - [`references/room-health-checks.md`](references/room-health-checks.md) — rules + remediation - [`references/room-graph-pipeline.md`](references/room-graph-pipeline.md) — Docker dashboard recipe - [`references/safety-guide.md`](references/safety-guide.md) — destructive-op checklist - Source: [netresearch/matrix-skill](https://github.com/netresearch/matrix-skill)