Room Commands#

synadm room#

Manipulate rooms and room membership.

The syntax of room IDs in synadm is as the Matrix spec defines: https://spec.matrix.org/latest/#room-structure. Make sure to escape the ! character from your shell. In bash and zsh this can be achieved by using single quotes (‘), eg. ‘!id123abc:matrix.DOMAIN’

synadm room [OPTIONS] COMMAND [ARGS]...

block#

Block or unblock a room.

synadm room block [OPTIONS] ROOM_ID

Options

-b, --block, -u, --unblock#

Specifies whether to block or unblock a room.

Default:

True

Arguments

ROOM_ID#

Required argument

block-status#

Get if a room is blocked, and who blocked it.

synadm room block-status [OPTIONS] ROOM_ID

Arguments

ROOM_ID#

Required argument

delete#

Delete and possibly purge a room.

By default, the v2 API is used, which will return a delete_id and delete the room asynchronously instead of waiting for a room to be deleted (the v1 API will wait for the room to be deleted). You can check the status of the room deletion with synadm room delete-status.

synadm room delete [OPTIONS] ROOM_ID

Options

-u, --new-room-user-id <new_room_user_id>#

If set, a new room will be created with this user ID as the creator and admin, and all users in the old room will be moved into that room. If not set, no new room will be created and the users will just be removed from the old room. The user ID must be on the local server, but does not necessarily have to belong to a registered user.

-n, --room-name <room_name>#

A string representing the name of the room that new users will be invited to. Defaults to “Content Violation Notification”

-m, --message <message>#

A string containing the first message that will be sent as new_room_user_id in the new room. Ideally this will clearly convey why the original room was shut down. Defaults to “Sharing illegal content on this server is not permitted and rooms in violation will be blocked.”

-b, --block#

If set, this room will be added to a blocking list, preventing future attempts to join the room

Default:

False

--no-purge#

Prevent removing of all traces of the room from your database.

Default:

False

--force-purge#

Force a purge to go ahead even if there are local users still in the room. Do not use this unless a regular purge operation fails, as it could leave those users’ clients in a confused state.

Default:

False

--v1#

Use version 1 of the room delete API instead of version 2, which will wait until the room deletion is complete.

Default:

False

Arguments

ROOM_ID#

Required argument

delete-status#

Get room deletion status via either the room ID or the delete ID.

This requires the usage of the Room Delete v2 API. If you used v1 of the Room Delete API, this is irrelevant.

synadm room delete-status [OPTIONS]

Options

-r, --room-id <room_id>#

The Room ID to query the deletion status for

-d, --delete-id <delete_id>#

The Delete ID to query the deletion status for

details#

Get room details.

synadm room details [OPTIONS] ROOM_ID

Arguments

ROOM_ID#

Required argument

join#

Join a room.

The administrator must belong to the room and have sufficient privilege to invite the user. If this is not the case, you can use the make-admin command.

synadm room join [OPTIONS] ROOM_ID_OR_ALIAS USER_ID

Arguments

ROOM_ID_OR_ALIAS#

Required argument

USER_ID#

Required argument

list#

List and search for rooms.

synadm room list [OPTIONS]

Options

-f, --from <from_>#

Offset room listing by given number. This option is used for pagination.

Default:

0

-l, --limit <limit>#

Maximum amount of rooms to return.

Default:

100

-n, --name <name>#

Filter rooms by parts of their room name, canonical alias and room id.

-s, --sort <sort>#

The method in which to sort the returned list of rooms.

Options:

name | canonical_alias | joined_members | joined_local_members | version | creator | encryption | federatable | public | join_rules | guest_access | history_visibility | state_events

-r, --reverse#

Direction of room order. If set it will reverse the sort order of –order-by method.

-e, --empty, -E, --not-empty#

Query for empty rooms only, or not empty rooms only. If unspecified, both empty and non-empty rooms are included.

make-admin#

Grant a user room admin permission.

If the user is not in the room, and it is not publicly joinable, then invite the user.

synadm room make-admin [OPTIONS] ROOM_ID

Options

-u, --user-id <user_id>#

By default the server admin (the caller) is granted power, but another user can optionally be specified.

Arguments

ROOM_ID#

Required argument

members#

List current room members.

synadm room members [OPTIONS] ROOM_ID

Arguments

ROOM_ID#

Required argument

power-levels#

List user’s power levels set in rooms.

A combination of commands room list and room state. It enriches the room list response with a list of users and their corresponding power levels set. It only displays a subset of the available information (room name, id, aliases and power levels). Increase the number of rooms fetched using –limit/-l (default: 10) or use the pagination option –from/-f to go beyond the default. Use –name/-n to search. This command can require quite some time to complete depending on those options.

synadm room power-levels [OPTIONS]

Options

-i, --room-id <room_id>#

View power levels of this room only.

-a, --all-details#

Show detailed information about each room. The default is to only show room_id, name, canonical_alias and power_levels.

-f, --from <from_>#

Offset room listing by given number. This option is used for pagination.

Default:

0

-l, --limit <limit>#

Maximum amount of rooms to return.

Default:

10

-n, --name <name>#

Filter rooms by parts of their room name, canonical alias and room id.

-s, --sort <sort>#

The method in which to sort the returned list of rooms.

Options:

name | canonical_alias | joined_members | joined_local_members | version | creator | encryption | federatable | public | join_rules | guest_access | history_visibility | state_events

-r, --reverse#

Direction of room order. If set it will reverse the sort order of –order-by method.

purge-empty#

Delete empty rooms (where 0 local members are currently in a room).

synadm room purge-empty [OPTIONS]

Options

--no-purge#

Prevent removing of all traces of the room from your database.

Default:

False

--force-purge#

Force a purge to go ahead even if there are local users still in the room. Do not use this unless a regular purge operation fails, as it could leave those users’ clients in a confused state.

Default:

False

--v1#

Use version 1 of the room delete API instead of version 2

Default:

False

--dry-run#

Only show the rooms IDs that will be deleted

-p, --batch-size, --paginate <batch_size>#

How many rooms should be requested from the API one at a time. This option has no effect on how many empty rooms will be deleted.

Increasing this is not necessary in most cases but useful if you have a lot of rooms on your homeserver.

Default:

100

resolve#

Lookup room ID from alias or vice versa.

synadm room resolve [OPTIONS] ROOM_ID_OR_ALIAS

Options

-r, --reverse#

Fetch all room aliases corresponding to a given room ID, instead of the other way round.

Default:

False

Arguments

ROOM_ID_OR_ALIAS#

Required argument

state#

Get a list of all state events in a room.

synadm room state [OPTIONS] ROOM_ID

Arguments

ROOM_ID#

Required argument