synapse-admin

Terminal UI for administering a Matrix Synapse homeserver over the Synapse Admin API.

The project is written in Go, builds as a single binary, and talks directly to the homeserver over HTTPS. The current UI is palette-first: ctrl+p is the main entry point for switching scope and opening config.

Inspired by yaky-dev/simple-synapse-admin, reworked here as a terminal-first Bubble Tea application.

Features

• ctrl+p command palette for scope switching and config access
• Users list with API-backed search
• Users next-page pagination plus local previous-page history
• User deactivate and reactivate actions with confirmation dialogs
• Rooms list with API-backed search
• Room delete action with force-purge retry on failure
• Registration token listing
• Config persistence in ~/.synapse-admin/config.toml
• Tolerant JSON decoding for Synapse responses that mix numbers and strings

Status

Implemented:

• Users scope
• Rooms scope
• Tokens scope
• Config dialog
• Confirm dialogs

Planned:

• Password reset dialog
• Members dialog
• Token create/delete flows
• Help overlay
• CI and release tooling

Screenshots

Command Palette

Config Dialog

Build

go build .

Create release archives:

make release

This produces:

• dist/synapse-admin_darwin_arm64.tar.gz
• dist/synapse-admin_linux_amd64.tar.gz
• dist/checksums.txt

Install

macOS with Homebrew

Recommended setup is a separate tap repository:

brew install dotlabshq/tap/synapse-admin

The formula is maintained in the separate tap repository:

github.com/dotlabshq/homebrew-tap

It installs the latest Apple Silicon macOS release binary from GitHub Releases.

Linux with curl

curl -fsSL https://raw.githubusercontent.com/dotlabshq/synapse-admin/main/scripts/install.sh | sh

The installer downloads the latest Linux x86_64 release binary from GitHub Releases and installs it into ~/.local/bin by default.

Run directly from source:

go run .

Run tests:

go test ./...

Configuration

Primary config path:

~/.synapse-admin/config.toml

Legacy fallback read path:

~/Library/Application Support/synapse-admin/config.toml

Config format:

[server]
homeserver = "https://matrix.example.com"
access_token = "syt_admin_xxxxxx"

Use the root homeserver URL, not an admin API path.

Keybindings

Global

Key	Action
ctrl+p	Open command palette
ctrl+s	Open config dialog
q / ctrl+c	Quit
esc	Close dialog or cancel filter

Navigation

Key	Action
↑ / k	Move up
↓ / j	Move down
n / →	Next page
p / ←	Previous page
enter	Confirm

Users

Key	Action
/	Search users through the Synapse API
x	Deactivate selected user
a	Reactivate selected user
r	Placeholder for password reset

Rooms

Key	Action
/	Search rooms through the Synapse API
d	Delete selected room
m	Placeholder for members dialog

Tokens

Key	Action
c	Placeholder for create token
d	Placeholder for delete token

Notes

• User reactivation is implemented with PUT /_synapse/admin/v2/users/{userId} and deactivated=false. Some Synapse deployments may require additional fields such as a new password.
• User pagination in Synapse is forward-only. The app provides previous navigation by keeping a local history of visited pages.
• Room deletion is asynchronous on the server side. A successful response means the delete task was accepted, not necessarily finished.
• Release assets are expected to be published with stable names: synapse-admin_darwin_arm64.tar.gz and synapse-admin_linux_amd64.tar.gz.