Welcome to synadm’s documentation!

Command Line Reference

Main Command

synadm

the Matrix-Synapse admin CLI

synadm [OPTIONS] COMMAND [ARGS]...

Options

-v, --verbose

enable INFO (-v) or DEBUG (-vv) logging on console

--batch, --no-batch

enable batch behavior (no interactive prompts)

-o, --output <output>

override default output format.

Options

yaml | json | human | pprint | y | j | h | p |

-c, --config-file <config_file>

configuration file path

Default

~/.config/synadm.yaml

Commands

config

Modify synadm’s configuration.

group

Manage groups (communities)

history

purge historic events from Synapse database

matrix

Execute Matrix API calls.

media

Manage local and remote media

room

Manipulate rooms and room membership

user

list, add, modify, deactivate/erase users,…

version

Get the synapse server version

User

synadm user

list, add, modify, deactivate/erase users, reset passwords

synadm user [OPTIONS] COMMAND [ARGS]...
deactivate

deactivate or gdpr-erase a user. Provide matrix user ID (@user:server) as argument. It removes active access tokens, resets the password, and deletes third-party IDs (to prevent the user requesting a password reset).

synadm user deactivate [OPTIONS] USER_ID

Options

-e, --gdpr-erase

marks the user as GDPR-erased. This means messages sent by the user will still be visible by anyone that was in the room when these messages were sent, but hidden from users joining the room afterwards.

Default

False

Arguments

USER_ID

Required argument

details

view details of a user account.

synadm user details [OPTIONS] USER_ID

Arguments

USER_ID

Required argument

list

list and search for users

synadm user list [OPTIONS]

Options

-f, --from <from_>

offset user listing by given number. This option is also used for pagination.

Default

0

-l, --limit <limit>

limit user listing to given number

Default

100

-g, --guests, -G, --no-guests

show guest users.

-d, --deactivated

also show deactivated/erased users

Default

False

-n, --name <name>

search users by name - filters to only return users with user ID localparts or displaynames that contain this value (localpart is the left part before the colon of the matrix ID (@user:server)

-i, --user-id <user_id>

search users by ID - filters to only return users with Matrix IDs (@user:server) that contain this value

login

Get an access token for a given user.

Useful for when admins wish to do actions on behalf of a user.

If no –expire* option is given, a default token expiry time of exactly 1 day (24h) is used. If it’s desired that the token never expires, use –expire-never

This API does not generate a new device for the user, and so will not appear in their /devices list, and in general the target user should not be able to tell they have been logged in as.

To expire the token before the expiry date/time is reached, call the standard /logout API with the token. Note: The token will expire if the admin user calls /logout/all from any of their devices, but the token will not expire if the target user does the same.

synadm user login [OPTIONS] USER_ID

Options

-d, --expire-days <expire_days>

expire token after this number of days.

--expire <expire>

expire token after this point in time. Eg. ‘2021-01-01’, see above for available date/time formats.

--expire-ts <expire_ts>

expire token after this point in time giving a unix timestamp in ms.

--expire-never

never expire token.

Default

False

Arguments

USER_ID

Required argument

media

list all local media uploaded by a user. Provide matrix user ID (@user:server) as argument.

Gets a list of all local media that a specific user_id has created. By default, the response is ordered by descending creation date and ascending media ID. The newest media is on top. You can change the order with options –order-by and –reverse.

Caution. The database only has indexes on the columns media_id, user_id and created_ts. This means that if a different sort order is used (upload_name, last_access_ts, media_length, media_type, quarantined_by or safe_from_quarantine), this can cause a large load on the database, especially for large environments

synadm user media [OPTIONS] USER_ID

Options

-f, --from <from_>

offset media listing by given number. This option is also used for pagination.

Default

0

-l, --limit <limit>

limit media listing to given number

Default

100

-s, --sort <sort>

The method by which to sort the returned list of media. If the ordered field has duplicates, the second order is always by ascending media_id, which guarantees a stable ordering.

Options

media_id | upload_name | created_ts | last_access_ts | media_length | media_type | quarantined_by | safe_from_quarantine

-r, --reverse

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

Arguments

USER_ID

Required argument

membership

list all rooms a user is member of. Provide matrix user ID (@user:server) as argument.

synadm user membership [OPTIONS] USER_ID

Arguments

USER_ID

Required argument

modify

create or modify a local user. Provide matrix user ID (@user:server) as argument.

synadm user modify [OPTIONS] USER_ID

Options

-p, --password-prompt

set password interactively.

-P, --password <password>

set password on command line.

-n, --display-name <display_name>

set display name. defaults to the value of user_id

-t, --threepid <threepid>

add a third-party identifier. This can be an email address or a phone number. Threepids are used for several things: For use when logging in, as an alternative to the user id. In the case of email, as an alternative contact to help with account recovery, as well as to receive notifications of missed messages. Format: medium value (eg. –threepid email <user@example.org>). This option can also be stated multiple times, i.e. a user can have multiple threepids configured.

-v, --avatar-url <avatar_url>

set avatar URL. Must be a MXC URI (https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris)

-a, --admin, -u, --no-admin

grant user admin permission. Eg user is allowed to use the admin API

--activate

re-activate user.

--deactivate

deactivate user. Use with caution! Deactivating a user removes their active access tokens, resets their password, kicks them out of all rooms and deletes third-party identifiers (to prevent the user requesting a password reset). See also “user deactivate” command.

Arguments

USER_ID

Required argument

password

change a user’s password. To prevent the user from being logged out of all sessions use option -n

synadm user password [OPTIONS] USER_ID

Options

-n, --no-logout

don’t log user out of all sessions on all devices.

-p, --password <password>

new password

Arguments

USER_ID

Required argument

whois

Return information about the active sessions for a specific user

synadm user whois [OPTIONS] USER_ID

Arguments

USER_ID

Required argument

Room

synadm room

Manipulate rooms and room membership

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

delete and possibly purge a room

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

Arguments

ROOM_ID

Required argument

details

get room details

synadm room details [OPTIONS] ROOM_ID

Arguments

ROOM_ID

Required argument

join

join a room

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 also used for pagination.

Default

0

-l, --limit <limit>

Maximum amount of rooms to return.

Default

100

-n, --name <name>

Filter rooms by their room name. Search term can be contained in any part of the room name)

-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.

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

Media

synadm media

Manage local and remote media

synadm media [OPTIONS] COMMAND [ARGS]...
delete

delete media by ID, size or age

synadm media delete [OPTIONS]

Options

-i, --media-id <media_id>

the media with this specific media ID will be deleted.

-d, --before-days <before_days>

delete all media that was last accessed before this number of days ago.

-b, --before <before>

delete all media that was last accessed before this date/time. Eg. ‘2021-01-01’, see above for available date/time formats.

-t, --before-ts <before_ts>

delete all media that was last accessed before this unix timestamp in ms.

--size, --kib <size>

delete all media that is larger than this size in KiB (1 KiB = 1024 bytes).

--delete-profiles, --all

also delete files that are still used in image data (e.g user profile, room avatar). If set, these files will be deleted too. Not valid when a specific media is being deleted (–media-id)

-s, --server-name <server_name>

your local matrix server name. Note: Currently this is a mandatory argument but will be automatically retrieved via the matrix API in the future.

list

list local media by room or user

synadm media list [OPTIONS]

Options

-r, --room-id <room_id>

list all media in room with this room ID (‘!abcdefg’).

-u, --user-id <user_id>

list all media uploaded by user with this matrix ID (@user:server).

-f, --from <from_>

offset media listing by given number. This option is also used for pagination but only supported together with –user-id.

Default

0

-l, --limit <limit>

limit media listing to given number. This option is only supported together with –user-id.

Default

100

-s, --sort <sort>

The method by which to sort the returned list of media. If the ordered field has duplicates, the second order is always by ascending media_id, which guarantees a stable ordering. This option is only supported together with –user-id.

Options

media_id | upload_name | created_ts | last_access_ts | media_length | media_type | quarantined_by | safe_from_quarantine

-R, --reverse

Direction of media order. If set it will reverse the sort order of –order-by method. This option is only supported together with –user-id.

protect

protect specific media from being quarantined

synadm media protect [OPTIONS] MEDIA_ID

Arguments

MEDIA_ID

Required argument

purge

Purge old cached remote media

synadm media purge [OPTIONS]

Options

-d, --before-days <before_days>

Purge all media that was last accessed before this number of days ago.

-b, --before <before>

Purge all media that was last accessed before this date/time. Eg. ‘2021-01-01’, see above for available date/time formats.

-t, --before-ts <before_ts>

Purge all media that was last accessed before this unix timestamp in ms.

quarantine

quarantine media in rooms, by users or by media ID

synadm media quarantine [OPTIONS]

Options

-i, --media-id <media_id>

the media with this specific media ID will be quarantined.

-r, --room-id <room_id>

all media in room with this room ID (!abcdefg) will be quarantined.

-u, --user-id <user_id>

all media uploaded by user with this matrix ID (@user:server) will be quarantined.

-s, --server-name <server_name>

the server name of the media, mandatory when –media-id is used.

History

synadm history

purge historic events from Synapse database

synadm history [OPTIONS] COMMAND [ARGS]...
purge

purge room events before a point in time or before an event ID.

The purge history API allows server admins to purge historic events from their database, reclaiming disk space.

Depending on the amount of history being purged a call to the API may take several minutes or longer. During this period users will not be able to paginate further back in the room from the point being purged from.

Note that Synapse requires at least one message in each room, so it will never delete the last message in a room.

By default, events sent by local users are not deleted, as they may represent the only copies of this content in existence. (Events sent by remote users are deleted.)

Room state data (such as joins, leaves, topic) is always preserved.

The API starts the purge running, and returns immediately with a JSON body with a purge id. Use ‘synadm history purge-status <purge id>’ to poll for updates on the running purge.

synadm history purge [OPTIONS] ROOM_ID

Options

-i, --before-event-id <before_event_id>

purge all history before this event ID. Event ID’s contain $, which is interpreted by the shell. Make sure it is surrounded by single quotes (‘id’).

-d, --before-days <before_days>

purge all history before this number of days ago.

--before <before>

purge all history before this point in time. Eg. ‘2021-01-01’, see above for available date/time formats.

--before-ts <before_ts>

purge all history before this point in time giving a unix timestamp in ms.

--delete-local

this option overrides the default behavior and forces removal of events sent by local users.

Arguments

ROOM_ID

Required argument

purge-status

view status of a recent history purge. Provide purge ID as argument.

The status will be one of active, complete, or failed.

synadm history purge-status [OPTIONS] PURGE_ID

Arguments

PURGE_ID

Required argument

Group

synadm group

Manage groups (communities)

synadm group [OPTIONS] COMMAND [ARGS]...
delete

delete a local group (community)

synadm group delete [OPTIONS] GROUP_ID

Arguments

GROUP_ID

Required argument

Python Package Documentation

Synadm CLI Package

The synadm.cli package contains all the command line frontend code (using the Python Click module), see the sections for each subcommand for help on usage and have a look into the files inside the synadm/cli directory to see how the CLI frontend is constructed. The main command is defined in __init__.py and each subcommand lives in its own module (e.g user.py, room.py, …)

Click command definition code is not very well suited for autogenerated Python package documentations (in this case using Sphinx autodoc) but one thing in this package that is worth mentioning and generating documentation for, is the synadm.cli.APIHelper class which is the connection between the CLI code and the backend code in synadm.api:

CLI base functions and settings

class synadm.cli.APIHelper(config_path, verbose, batch, output_format_cli)

Bases: object

API client enriched with CLI-level functions, used as a proxy to the client object

FORMATTERS = {'human': <function humanize>, 'json': <function dumps>, 'pprint': <function pformat>, 'yaml': <function dump>}
CONFIG = {'admin_path': '/_synapse/admin', 'base_url': 'http://localhost:8008', 'matrix_path': '/_matrix', 'timeout': 7, 'token': '', 'user': ''}
init_logger(verbose)

Log both to console (defaults to WARNING) and file (DEBUG)

_set_formatter(_output_format)
load()

Load the configuration and initialize the client

write_config(config)

Write a new version of the configuration to file

output(data)

Output data object using the configured formatter

Synadm Package

The synadm package contains the synadm.api module which is responsible for accessing the Synapse admin API endpoints and the regular Matrix API endpoints. Also some helper methods, e.g to calculate time-related things are to be found in this module:

Synapse admin API and regular Matrix API clients

Most API calls defined in this module respect the API’s defaults and only pass what’s necessary in the request body.

A fully qualified Matrix user ID looks like this: @user:server, where server often is a domain name only, e.g @user@example.org

See https://github.com/matrix-org/synapse/tree/master/docs/admin_api for documentation of the Synapse admin APIs and the Matrix spec at https://matrix.org/docs/spec/#matrix-apis.

class synadm.api.ApiRequest(log, user, token, base_url, path, timeout, debug)

Bases: object

Basic API request handling and helper utilities

This is subclassed by SynapseAdmin and Matrix

query(method, urlpart, params=None, data=None, token=None)

Generic wrapper around requests methods

Handles requests methods, logging and exceptions

Parameters

  • urlpart (string) – the path to the API endpoint, excluding self.base_url and self.path (the part after proto://fqdn:port/path).

  • params (dict, optional) – URL parameters (?param1&paarm2). Defaults to None.

  • data (dict, optional) – request body used in POST, PUT, DELETE requests. Defaults to None.

Returns

usually a JSON string containing

the response of the API; responses that are not 200(OK) (usally error messages returned by the API) will also be returned as JSON strings; on exceptions the error type and description are logged and None is returned.

Return type

string or None

_timestamp_from_days_ago(days)

Get a unix timestamp in ms from days ago

Parameters

days (int) – number of days

Returns

a unix timestamp in milliseconds (ms)

Return type

int

_timestamp_from_days_ahead(days)

Get a unix timestamp in ms for the given number of days ahead

Parameters

days (int) – number of days

Returns

a unix timestamp in milliseconds (ms)

Return type

int

_timestamp_from_datetime(_datetime)

Get a unix timestamp in ms from a datetime object

Parameters

_datetime (datetime object) – an object built by datetime.datetime

Returns

a unix timestamp in milliseconds (ms)

Return type

int

_datetime_from_timestamp(timestamp)

Get a datetime object from a unix timestamp in ms

Parameters

timestamp (int) – a unix timestamp in milliseconds (ms)

Returns

an object built by datetime.datetime

Return type

datetime object

class synadm.api.Matrix(log, user, token, base_url, matrix_path, timeout, debug)

Bases: synadm.api.ApiRequest

Matrix API client

Inheritance:
ApiRequest (object): parent class containing general properties and

methods for requesting REST API’s

user_login(user_id, password)

Login as a Matrix user and retrieve an access token

Parameters

  • user_id (string) – a fully qualified Matrix user ID

  • password (string) – the Matrix user’s password

Returns

JSON string containing a token suitable to access the

Matrix API on the user’s behalf, a device_id and some more details on Matrix server and user.

Return type

string

raw_request(endpoint, method, data, token=None)
class synadm.api.SynapseAdmin(log, user, token, base_url, admin_path, timeout, debug)

Bases: synadm.api.ApiRequest

Synapse admin API client

Inheritance:
ApiRequest (object): parent class containing general properties and

methods for requesting REST API’s

user_list(_from, _limit, _guests, _deactivated, _name, _user_id)

List and search users

Parameters

  • _from (int) – offsets user list by this number, used for pagination

  • _limit (int) – maximum number of users returned, used for pagination

  • _guests (bool) – enable/disable fetching of guest users

  • _deactivated (bool) – enable/disable fetching of deactivated users

  • _name (string) – user name localpart to search for, see Synapse admin API docs for details

  • _user_id (string) – fully qualified Matrix user ID to search for

Returns

JSON string containing the found users

Return type

string

user_membership(user_id)

Get a list of rooms the given user is member of

Parameters

user_id (string) – fully qualified Matrix user ID

Returns

JSON string containing the admin API’s response or None if

an exception occured. See Synapse admin API docs for details.

Return type

string

user_deactivate(user_id, gdpr_erase)

Delete a given user

Parameters

  • user_id (string) – fully qualified Matrix user ID

  • gdpr_erase (bool) – enable/disable gdpr-erasing the user, see Synapse admin API docs for details.

Returns

JSON string containing the admin API’s response or None if

an exception occured. See Synapse admin API docs for details.

Return type

string

user_password(user_id, password, no_logout)

Set the user password, and log the user out if requested

Parameters

  • user_id (string) – fully qualified Matrix user ID

  • password (string) – new password that should be set

  • no_logout (bool) – the API defaults to logging out the user after password reset via the admin API, this option can be used to disable this behaviour.

Returns

JSON string containing the admin API’s response or None if an exception occured. See Synapse admin API docs for details.

Return type

string

user_details(user_id)

Get information about a given user

Note that the admin API docs describe this function as “Query User Account”.

Parameters

user_id (string) – fully qualified Matrix user ID

Returns

JSON string containing the admin API’s response or None if

an exception occured. See Synapse admin API docs for details.

Return type

string

user_login(user_id, expire_days, expire, _expire_ts)

Get an access token that can be used to authenticate as that user.

If one of the args expire_days, expire or _expire_ts is set, the valid_until_ms field will be sent to the API endpoint. If this is not the case the default of the API would be used. At the time of writing, this would be that tokens never expire.

Note: If this method is called by the CLI frontend code (synadm.cli.user.user_login_cmd), a default expiry date of 1 day (24h) is passed.

Parameters

  • user_id (string) – fully qualified Matrix user ID

  • expire_days (int) – token should expire after this number of days

  • expire (datetime) – token should expire after this date/time - a datetime object (e.g. as generated by Click.DateTime())

  • _expire_ts (int) – token should expire after this date/time - a unix timestamp in ms.

Returns

JSON string containing the admin API’s response or None if an exception occured. See Synapse admin API docs for details.

Return type

string

user_modify(user_id, password, display_name, threepid, avatar_url, admin, deactivation)

Create or update information about a given user

Threepid should be passed as a tuple in a tuple

user_whois(user_id)

Return information about the active sessions for a specific user

room_join(room_id_or_alias, user_id)

Allow an administrator to join an user account with a given user_id to a room with a given room_id_or_alias

room_list(_from, limit, name, order_by, reverse)

List and search rooms

room_details(room_id)

Get details about a room

room_members(room_id)

Get a list of room members

room_delete(room_id, new_room_user_id, room_name, message, block, no_purge)

Delete a room and purge it if requested

room_make_admin(room_id, user_id)

Grant a user room admin permission. If the user is not in the room, and it is not publicly joinable, then invite the user.

room_media_list(room_id)

Get a list of known media in an (unencrypted) room.

media_quarantine(server_name, media_id)

Quarantine a single piece of local or remote media

room_media_quarantine(room_id)

Quarantine all local and remote media in a room

user_media_quarantine(user_id)

Quarantine all local and remote media of a user

user_media(user_id, _from, limit, order_by, reverse)

Get a user’s uploaded media

media_delete(server_name, media_id)

Delete a specific (local) media_id

media_delete_by_date_or_size(server_name, before_days, before, _before_ts, _size_gt, delete_profiles)

Delete local media by date and/or size FIXME and/or?

media_protect(media_id)

Protect a single piece of local or remote media

from being quarantined

purge_media_cache(before_days, before, _before_ts)

Purge old cached remote media

version()

Get the server version

group_delete(group_id)

Delete a local group (community)

purge_history(room_id, before_event_id, before_days, before, _before_ts, delete_local)

Purge room history

purge_history_status(purge_id)

Get status of a recent history purge

The status will be one of active, complete, or failed.

Indices and tables