Commands

Commands are the commands listed below, e.g. adduser to create a new user on the homeserver or deploy to deploy the ansible playbook.

adduser

Use this module to add the adduser subcommand to matrixctl.

matrixctl.commands.adduser.parser.subparser_adduser(subparsers, common_parser)[source]

Create a subparser for the matrixctl adduser command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the adduser subcommand to matrixctl.

matrixctl.commands.adduser.addon.addon(arg, yaml)[source]

Add a User to the synapse instance.

It runs ask_password() first. If ask_password() returns None it generates a password with gen_password(). Then it gives the user a overview of the username, password and if the new user should be generated as admin (if you added the --admin argument). Next, it asks a question, if the entered values are correct with the ask_question function.

If the ask_question function returns True, it continues. If not, it starts from the beginning.

Depending on the --ansible switch it runs the adduser command via ansible or the API

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

deluser

Use this module to add the deluser subcommand to matrixctl.

matrixctl.commands.deluser.parser.subparser_deluser(subparsers, common_parser)[source]

Create a subparser for the matrixctl deluser command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the deluser subcommand to matrixctl.

matrixctl.commands.deluser.addon.addon(arg, yaml)[source]

Delete a user from the the matrix instance.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

check

Use this module to add the check subcommand to matrixctl.

matrixctl.commands.check.parser.subparser_check(subparsers, common_parser)[source]

Create a subparser for the matrixctl check command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the check subcommand to matrixctl.

matrixctl.commands.check.addon.addon(_, yaml)[source]

Check the deployment with andible.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

deploy

Use this module to add the deploy subcommand to matrixctl.

matrixctl.commands.deploy.parser.subparser_deploy(subparsers, common_parser)[source]

Create a subparser for the matrixctl deploy command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the deploy subcommand to matrixctl.

matrixctl.commands.deploy.addon.addon(arg, yaml)[source]

Deploy the ansible playbook.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

largest-rooms

Use this module to estimate the largest rooms from the database.

matrixctl.commands.largest_rooms.parser.subparser_rooms(subparsers, common_parser)[source]

Create a subparser for the matrixctl largest-rooms command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to list an approximation of the largest rooms.

matrixctl.commands.largest_rooms.addon.addon(arg, yaml)[source]

Generate a table of the top 10 matrix rooms in terms of DB storage.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

matrixctl.commands.largest_rooms.addon.generate_output(rooms, *, to_json)[source]

Use this helper to generate the output.

Return type:

None

Parameters:
roomslist of matrixctl.typehints.JsonDict

A list of rooms from the API.

to_jsonbool

True, when the output should be in the JSON format. False, when the output should be a table.

Returns:
None

Use this module to add the rooms subcommand to matrixctl.

matrixctl.commands.largest_rooms.to_table.format_bytes(size)[source]

Format bytes (storage) into a string using the correct prefix.

Return type:

str

Parameters:
sizeint

An integer representing some storage size in bytes

Returns:
formattedstr

The size formatted with a prefix of bytes.

matrixctl.commands.largest_rooms.to_table.to_table(rooms_list)[source]

Use this function as helper to pint the largest-room table.

Return type:

Generator[str, None, None]

Parameters:
rooms_listlist of matrixctl.typehints.JsonDict

A list of rooms from the API.

Yields:
table_linesstr

The table lines.

maintenance

Use this module to add the maintenance subcommand to matrixctl.

matrixctl.commands.maintenance.parser.subparser_maintenance(subparsers, common_parser)[source]

Create a subparser for the matrixctl maintenance command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the maintenance subcommand to matrixctl.

class matrixctl.commands.maintenance.addon.Task(*values)[source]

Bases: Enum

Use this enum for describing the maintenance task.

Supported tasks:

tasks

Description

vacuum

Reclaims storage occupied by dead tuples.

compress_state

Compress Synapse State Tables.
COMPRESS_STATE = 'rust-synapse-compress-state'
VACUUM = 'run-postgres-vacuum'
matrixctl.commands.maintenance.addon.addon(arg, yaml)[source]

Run the maintenance procedure of the ansible playbook.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

matrixctl.commands.maintenance.addon.print_tasks()[source]

Print a list of all available tasks.

Return type:

None

start

Use this module to add the (re)start subcommand to matrixctl.

matrixctl.commands.start.parser.subparser_restart(subparsers, common_parser)[source]

Create a subparser for the matrixctl restart command.

Parameters:
subparsersargparse._SubParsersAction or typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

See also

matrixctl.start.subparser_start

Subparser for matrixctl start.

Notes

This is a alias for matrixctl start

matrixctl.commands.start.parser.subparser_start(subparsers, common_parser)[source]

Create a subparser for the matrixctl start command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the (re)start subcommand to matrixctl.

matrixctl.commands.start.addon.addon(_, yaml)[source]

Start/Restart the OCI containers.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

stop

Use this module to add the stop subcommand to matrixctl.

matrixctl.commands.stop.parser.subparser_stop(subparsers, common_parser)[source]

Create a subparser for the matrixctl stop command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the stop subcommand to matrixctl.

matrixctl.commands.stop.addon.addon(_, yaml)[source]

Stop the OCI containers.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

update

Use this module to add the update subcommand to matrixctl.

matrixctl.commands.update.parser.subparser_update(subparsers, common_parser)[source]

Create a subparser for the matrixctl update command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the update subcommand to matrixctl.

matrixctl.commands.update.addon.addon(_, yaml)[source]

Update the synapse playbook with git.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

user

Use this module to add the user subcommand to matrixctl.

matrixctl.commands.user.parser.subparser_user(subparsers, common_parser)[source]

Create a subparser for the matrixctl user command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the user subcommand to matrixctl.

matrixctl.commands.user.addon.addon(arg, yaml)[source]

List information about an registered user.

It uses the admin API to get a python dictionary with the information. The generate_user_tables function makes the information human readable.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

Examples

$ matrixctl user dwight
User:
+----------------------------+--------------------------------------+
| Name                       | dwight                               |
| Password Hash              | $2b$12$9DUNderm1ffL1NincPap3RC       |
|                            | ompaNY1725.slOUghAvEnu5cranT0n       |
| Guest                      | False                                |
| Admin                      | True                                 |
| Consent Version            |                                      |
| Consent Server Notice Sent |                                      |
| Appservice Id              |                                      |
| Creation Ts                | 2020-04-14 13:04:21                  |
| User Type                  |                                      |
| Deactivated                | False                                |
| Displayname                | Dwight Schrute                       |
| Avatar Url                 | mxc://dunder-mifflin.com/sCr4        |
|                            | nt0nsr4ng13rW45Cr33d                 |
+----------------------------+--------------------------------------+

Threepid:
+--------------+-----------------------------------+
| Medium       | email                             |
| Address      | dwight_schrute@dunder-mifflin.com |
| Validated At | 2020-04-14 15:30:21.123000        |
| Added At     | 2020-04-14 15:29:19.100000        |
+--------------+-----------------------------------+

If the user does not exist, the return looks like:

Use this module to add the rooms subcommand to matrixctl.

matrixctl.commands.user.to_table.generate_user_tables(user_dict, len_domain)[source]

Generate a main user table and threepid user tables.

The function gnerates first a main user table and then for every threepid a additional table from a user_dict. It renames and makes the output human readable.

Return type:

list[list[tuple[str, str]]]

Parameters:
user_dictdict [str, typing.Any]

The line as dict, a JSON string which was converted to a Python dictionary. (This is not a Collections.UserDict)

len_domainint

The length in characters of the domain.

Returns:
err_codeint

A list in the format: [[main], threepids_0, ... ,threepids_n]

Notes

This function is a recursive function.

matrixctl.commands.user.to_table.make_human_readable(k, user_dict, len_domain)[source]

Make a key/value pair of a user (line) human readable, by modifying.

Return type:

tuple[str, str]

Parameters:
kstr

The key

user_dictdict [str, typing.Any]

The line as dict, a JSON string which was converted to a Python dictionary. (This is not a Collections.UserDict)

len_domainint

The length in characters of the domain.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

Notes

This function is used as helper by matrixctl.user.generate_user_tables.

matrixctl.commands.user.to_table.to_table(user_dict, len_domain)[source]

Use this function as helper to pint the room table.

Return type:

Generator[str, None, None]

Parameters:
user_dictmatrixctl.typehints.JsonDict

The user data from the API

len_domainint

The length of the homeservers domain.

Yields:
table_linesstr

The table lines.

users

Use this module to add the users subcommand to matrixctl.

matrixctl.commands.users.parser.subparser_users(subparsers, common_parser)[source]

Create a subparser for the matrixctl users command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the users subcommand to matrixctl.

matrixctl.commands.users.addon.addon(arg, yaml)[source]

Print a table/json of the matrix users.

This function generates and prints a table of users or uses json as output format.

The table can be modified.

  • If you want guests in the table use the --with-guests switch.

  • If you want deactivated user in the table use the --with-deactivated switch.

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

rtype:

int ..

Notes

  • Needs API version 2 (synapse 1.28 or greater) to work.

  • API version 1 is deprecated. If you encounter problems please upgrade to the latest synapse release.

Use this module to add the rooms subcommand to matrixctl.

matrixctl.commands.users.to_table.to_table(users_list, len_domain)[source]

Use this function as helper to pint the users table.

Return type:

Generator[str, None, None]

Parameters:
users_listlist of matrixctl.typehints.JsonDict

A list of rooms from the API.

len_domainint

The length of the homeservers domain.

Yields:
table_linesstr

The table lines.

Examples

$ matrixctl users
+---------+-------------+---------------+-------+-------+--------------+
| Name    | Deactivated | Shadow-Banned | Admin | Guest | Display Name |
|---------+-------------+---------------+-------+-------|--------------+
| dwight  | No          | No            | Yes   | No    | Dwight       |
| pam     | No          | No            | No    | No    | Pam          |
| jim     | No          | No            | No    | No    | Jim          |
| creed   | No          | Yes           | No    | No    | Creed        |
| stanley | No          | No            | No    | No    | Stanley      |
| kevin   | No          | No            | No    | No    | Cookie       |
| angela  | No          | No            | No    | No    | Angela       |
| phyllis | No          | No            | No    | No    | Phyllis      |
| tobi    | No          | No            | No    | No    | TobiHR       |
| michael | No          | No            | Yes   | No    | Best Boss    |
| andy    | No          | No            | No    | No    | Andy         |
+---------+-------------+---------------+-------+-------+--------------+

report

Use this module to add the report subcommand to matrixctl.

matrixctl.commands.report.parser.subparser_report(subparsers, common_parser)[source]

Create a subparser for the matrixctl report command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the users subcommand to matrixctl.

matrixctl.commands.report.addon.addon(arg, yaml)[source]

Print a table of the reported events.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

reports

Use this module to add the reports subcommand to matrixctl.

matrixctl.commands.reports.parser.subparser_reports(subparsers, common_parser)[source]

Create a subparser for the matrixctl reports command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the reports subcommand to matrixctl.

matrixctl.commands.reports.addon.addon(arg, yaml)[source]

Print a table/json of the reported events.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

Use this module to add the rooms subcommand to matrixctl.

matrixctl.commands.reports.to_table.to_table(events_raw)[source]

Use this function as helper to pint the events as table.

Return type:

Generator[str, None, None]

Parameters:
events_rawlist of matrixctl.typehints.JsonDict

A list of events from the API.

Yields:
table_linesstr

The table lines.

Examples

$ matrixctl reports
+-----------------+----------------------------------------------+
| ID              | 2                                            |
| Date            | 2021-05-08                                   |
| Time            | 21:04:55                                     |
| Score           | -100                                         |
| Canonical Alias | -                                            |
| Room Name       | SomeRoom                                     |
| Room ID         | !AbCdEfGhIjKlMnOpQr:domain.tld               |
| Event ID        | $Q_sksd348jaidj93jf9ojwef9h329ofijewhf932h9f |
| Defendant       | @mallory:matrix.org                          |
| Plaintiff       | @alice:myhomeverver.tld                      |
| Reason          | Likes JavaScript                             |
|-----------------+----------------------------------------------|
| ID              | 1                                            |
| Date            | 2020-08-15                                   |
| Time            | 09:09:57                                     |
| Score           | -100                                         |
| Canonical Alias | -                                            |
| Room Name       | -                                            |
| Room ID         | !AbCdEfGhIjKlMnOpQr:matrix.org               |
| Event ID        | $123456789012345678901:matrix.org            |
| Defendant       | @eve:matrix.org                              |
| Plaintiff       | @bob:myhomeserver.tld                        |
| Reason          | Hates The Office (US)                        |
+-----------------+----------------------------------------------+

rooms

Use this module to add the rooms subcommand to matrixctl.

matrixctl.commands.rooms.parser.subparser_rooms(subparsers, common_parser)[source]

Create a subparser for the matrixctl rooms command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the rooms subcommand to matrixctl.

matrixctl.commands.rooms.addon.addon(arg, yaml)[source]

Generate a table of the matrix rooms.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

matrixctl.commands.rooms.addon.filter_empty_rooms(rooms, *, local_users=True)[source]

Filter for empty rooms.

Return type:

list[dict[str, Any]]

Parameters:
roomslist of matrixctl.typehints.JsonDict

A rooms list.

local_usersbool

true: Filter, if no local user is in the room. false: Filter, if no user is in the room.

Returns:
roomslist of matrixctl.typehints.JsonDict

The filtered list.

matrixctl.commands.rooms.addon.generate_output(rooms, *, to_json)[source]

Use this helper to generate the output.

Return type:

None

Parameters:
roomslist of matrixctl.typehints.JsonDict

A list of rooms from the API.

to_jsonbool

True, when the output should be in the JSON format. False, when the output should be a table.

Returns:
None

Use this module to add the rooms subcommand to matrixctl.

matrixctl.commands.rooms.to_table.to_table(rooms_list)[source]

Use this function as helper to pint the room table.

Return type:

Generator[str, None, None]

Parameters:
rooms_listlist of matrixctl.typehints.JsonDict

A list of rooms from the API.

Yields:
table_linesstr

The table lines.

purge-history

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.commands.purge_history.parser.subparser_purge_history(subparsers, common_parser)[source]

Create a subparser for the matrixctl purge-history command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.commands.purge_history.addon.addon(arg, yaml)[source]

Purge historic message events from the Database.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.commands.purge_history.dialog.dialog_input(arg)[source]

Ask questions and sanitize them.

Return type:

dict[str, str | int]

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

Returns:
request_bodytyping.Dict [str, str] or NoReturn

Non-zero value indicates error code, or zero on success.

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.commands.purge_history.handler.handle_purge_status(yaml, purge_id)[source]

Check the status of the purge history request.

Return type:

int

Parameters:
yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

purge_id: str

The purge id from a purge history request.

Returns:
response: matrixctl.typehints.JsonDict, optional

The response as dict, containing the status.

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.commands.purge_history.timing.check_point_in_time(event_or_timestamp)[source]

Check the the type of the point in time and set the correct body.

Return type:

dict[str, str | int] | None

Parameters:
event_or_timestampstr

The event_id or timestamp (UNIX epoch, in milliseconds).

Returns:
request_body: Dict [str, str or int]

A dict, which can be merged with the request_body dict.

delroom

Use this module to add the delroom subcommand to matrixctl.

matrixctl.commands.delroom.parser.subparser_delroom(subparsers, common_parser)[source]

Create a subparser for the matrixctl delroom command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the delroom subcommand to matrixctl.

matrixctl.commands.delroom.addon.addon(arg, yaml)[source]

Delete an empty room from the database.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

matrixctl.commands.delroom.addon.handle_arguments(arg)[source]

Build the parameters used for the delroom request.

Return type:

dict[str, Any]

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

Returns:
bodymatrixctl.typehints.JsonDict

The params.

matrixctl.commands.delroom.addon.handle_status(yaml, delete_id)[source]

Handle the status of a delete room request.

Return type:

dict[str, Any]

Parameters:
yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

delete_id: str

The delete id of a delete room request.

Returns:
response: matrixctl.typehints.JsonDict, optional

The response as dict, containing the status.

upload

Use this module to add the upload subcommand to matrixctl.

matrixctl.commands.upload.parser.subparser_upload(subparsers, common_parser)[source]

Create a subparser for the matrixctl upload command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the upload subcommand to matrixctl.

matrixctl.commands.upload.addon.addon(arg, yaml)[source]

Upload a file or image to the matrix instance.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

download

Use this module to add the download subcommand to matrixctl.

matrixctl.commands.download.parser.subparser_download(subparsers, common_parser)[source]

Create a subparser for the matrixctl download command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the download subcommand to matrixctl.

matrixctl.commands.download.addon.addon(arg, yaml)[source]

Download a file or image from the matrix instance.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

server-notice

Use this module to add the serve-notice subcommand to matrixctl.

matrixctl.commands.server_notice.parser.subparser_server_notice(subparsers, common_parser)[source]

Create a subparser for the matrixctl server-notice command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the serve-notice subcommand to matrixctl.

matrixctl.commands.server_notice.addon.addon(arg, yaml)[source]

Send a server notice to a matrix instance.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args().

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

Notes

  • It uses the synapse admin API.

  • Note that “server notices” must be enabled in homeserver.yaml before this API can be used.

get-event

Use this module to get an event from the Database.

matrixctl.commands.get_event.parser.subparser_get_event(subparsers, common_parser)[source]

Create a subparser for the matrixctl get-event command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to get an event from the Database.

matrixctl.commands.get_event.addon.addon(arg, yaml)[source]

Get an Event from the Server.

It connects via paramiko to the server and runs the psql command provided by the synapse playbook to run a query on the Database.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

get-events

Use this module to get an events of an user from the Database.

class matrixctl.commands.get_events.parser.OutputType(*values)[source]

Bases: Enum

Use this enum for describing the possible output types.

Supported output types are:

Output Type

Description

rows

Output raw JSON.

json

Output only a summary as row.
JSON = 'json'
ROWS = 'rows'
matrixctl.commands.get_events.parser.subparser_get_events(subparsers, common_parser)[source]

Create a subparser for the matrixctl get-event command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to get an event from the Database.

matrixctl.commands.get_events.addon.add_tuple_to_query_workaround(query, values, args, token)[source]

Use this function as a workaround for adding a tuple to the query.

Return type:

tuple[str, list[str | int | tuple[str | int, ...]]]

matrixctl.commands.get_events.addon.addon(arg, yaml)[source]

Get Events from the Server.

It connects via paramiko to the server and runs the psql command provided by the synapse playbook to run a query on the Database.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

matrixctl.commands.get_events.addon.output_as_json(cur)[source]

Output the events as JSON.

Return type:

int

matrixctl.commands.get_events.addon.output_as_rows(cur, yaml)[source]

Output the events as rows.

Return type:

int

joinroom

Use this module to add the joinroom subcommand to matrixctl.

matrixctl.commands.joinroom.parser.subparser_deluser(subparsers, common_parser)[source]

Create a subparser for the matrixctl joinroom command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the joinroom subcommand to matrixctl.

matrixctl.commands.joinroom.addon.addon(arg, yaml)[source]

Join a user to an room.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

Notes

  • You can only modify the membership of local users.

  • The the token of server administrator used to authenticate against the homeserver must be in the room and must have permission to invite users.

is-admin

Use this module to add the is-admin subcommand to matrixctl.

matrixctl.commands.is_admin.parser.subparser_is_admin(subparsers, common_parser)[source]

Create a subparser for the matrixctl is-admin command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to add the is-admin subcommand to matrixctl.

matrixctl.commands.is_admin.addon.addon(arg, yaml)[source]

Delete a user is an admin.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

Notes

If a user does not exist it still will return "admin": false or No.

set-admin

Use this module to add the set-admin subcommand to matrixctl.

matrixctl.commands.set_admin.parser.subparser_set_admin(subparsers, common_parser)[source]

Create a subparser for the matrixctl set-admin command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to get the number of user in a Matrix room.

matrixctl.commands.set_admin.addon.addon(arg, yaml)[source]

Change whether a user is an admin or not.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

make-room-admin

Add the make-room-admin subcommand to matrixctl.

matrixctl.commands.make_room_admin.parser.subparser_make_room_admin(subparsers, common_parser)[source]

Create a subparser for the matrixctl make-room-admin command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to grant a user room admin status.

Grant another user the highest power available to a local user who is in the room Matrix room.

matrixctl.commands.make_room_admin.addon.addon(arg, yaml)[source]

Grant a user room admin status.

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

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

get-event-context

Add the get-event-context subcommand to matrixctl.

matrixctl.commands.get_event_context.parser.subparser_get_event_context(subparsers, common_parser)[source]

Create a subparser for the matrixctl get-event-context command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to find the context of an event.

matrixctl.commands.get_event_context.addon.addon(arg, yaml)[source]

Find the context of an event.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

purge-remote-media

Add the purge-remote-media subcommand to matrixctl.

matrixctl.commands.purge_remote_media.parser.subparser_purge_remote_media(subparsers, common_parser)[source]

Create a subparser for the matrixctl purge-remote-media command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to delete remote media.

matrixctl.commands.purge_remote_media.addon.addon(arg, yaml)[source]

Remove remote media.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

matrixctl.commands.purge_remote_media.addon.handle_timestamp(timestamp, *, force)[source]

Ask or generate timestamp.

Return type:

int

Parameters:
timestampint, optional

The timestamp

forcebool

Don’t ask any questions. All questions are answered with True.

Returns:
timestampint

The same timestamp but sanitized, or the timestamp of this exact time.

delete-local-media

Add the delete-local_media subcommand to matrixctl.

matrixctl.commands.delete_local_media.parser.subparser_delete_local_media(subparsers, common_parser)[source]

Create a subparser for the matrixctl delete-local_media command.

Parameters:
subparsersargparse._SubParsersAction of typing.Any

The object which is returned by parser.add_subparsers().

Returns:
None

Use this module to delete local media.

matrixctl.commands.delete_local_media.addon.addon(arg, yaml)[source]

Delete local media.

Return type:

int

Parameters:
argargparse.Namespace

The Namespace object of argparse’s parse_args()

yamlmatrixctl.handlers.yaml.YAML

The configuration file handler.

Returns:
err_codeint

Non-zero value indicates error code, or zero on success.

matrixctl.commands.delete_local_media.addon.handle_timestamp(timestamp, *, force)[source]

Ask or generate timestamp.

Return type:

int

Parameters:
timestampint, optional

The timestamp

forcebool

Don’t ask any questions. All questions are answered with True.

Returns:
timestampint

The same timestamp but sanitized, or the timestamp of this exact time.