Matricks: tricks (tools) for Matrix

a small collection of tools for Matrix...

Usage

First you need to already have an access token and URL for your homeserver. Then expose them as env vars, e.g. with the following shell snippet. (You could also put this in a file and source it with . matricks_auth.sh if desired!)

read MATRICKS_HOMESERVER # enter your homeserver, e.g. https://matrix.librepush.net
read MATRICKS_TOKEN # enter your access token
export MATRICKS_HOMESERVER MATRICKS_TOKEN

Space tools

space tree: List a space hierarchy from a root space

You just need to provide a room ID or room alias for the root space.

matricks space tree #myspace:example.org

The output of this command is a restricted Markdown subset, suitable both for human reading and for use in later commands as a Room Batch File.

Room tools

All these commands take a source of room IDs, either a single room ID as --one !roomid:example.com, or a list of room IDs from a Room Batch File as --file path/to/file.md. This room source argument should be before the next subcommand.

rooms aliases: List aliases from rooms

matricks rooms --one '!roomid:example.org` aliases --if-not-match '#nomatch.*' --if-match '#[0-9a-f]*:.*'

The --if-match and --if-not-match predicates arguments can be specified multiple times and let you specify regular expressions to match aliases to include or omit, respectively. When multiple predicates are specified, ALL predicates must be satisfied (i.e. it's a big logical AND across all of them).

rooms make-read-only: Make a room read-only

matricks rooms --one '!roomid:example.org` make-read-only --power-level 50

This command makes the specified room(s) effectively read-only to unprivileged users by updating the m.room.power_levels state event to:

• set event_default to at least the threshold PL
• set all event types' required power level to at least the threshold PL

The --power-level argument specifies the threshold power level (PL); that is, which power level or higher is allowed to send events from now on.

Room Alias Tools

All these commands take a source of room aliases, either a single room alias as --one #room:example.com, or a list of room aliases from an Alias Batch File as --file path/to/file.md. This room source argument should be before the next subcommand.

aliases remove: Remove room aliases

matricks aliases --one '#room:example.org' remove

This command removes the specified room alias(es).

File Formats

Room Batch File

A Room Batch File is a Markdown file that conveniently happens to contain Room IDs embedded in backticks (i.e. code segments).

Room IDs must not split across lines. The position and formatting of Room IDs is otherwise unimportant.

Example

Text text text `!room:example.org`

- Text text text `!room2:example.org`
  - Text text text `!room3:example.org`

Alias Batch File

This is the same as a Room Batch File, but instead of room IDs, it contains room aliases.

Example

- Some room `#room:example.org`
- Some room 2 `#room2:example.org`