matrixtool client - Commandline client utilities for a Matrix homeserver


   $ matrixtool client login


This command provides a commandline interface to various client APIs on a Matrix homeserver. It has various sub-commands that provide particular functionality, along with some common options between them.

These sub-commands offers a convenience over using simpler tools like curl directly because they will automatically fill in details like access tokens and server hostnames, when given a user-id argument. This works by storing a cache of access tokens in the user's home directory, under .matrix/client-tokens.

By using the matrixtool client login command you can add an access token for your user account into this cache:

   $ matrixtool client login
   [OK] Obtained access token

Having logged in, you can now use the -u option to other matrixtool client subcommands, causing it to automatically supply this access token on every request:

   $ matrixtool client -u json /_matrix/client/r0/publicRooms


The following additional options are recognised

--user-id, -u

User ID to supply the access_token of.

--user-id-parameter, -U

User ID to set as the value of the user_id HTTP query parameter. This is usually only useful for controlling application service ghosted users.

--server, -s

Server to connect to. Usually optional, as it is implied by the user-id if provided.


The following sub-commands are recognised


Perform a direct JSON request

   $ matrixtool client json PATH [DATA]

See also App::MatrixTool::Command::client::json.


Obtain a client authentication token

   $ matrixtool client login USER-ID

See also App::MatrixTool::Command::client::login.


Upload a file to the media repository

   $ matrixtool client upload FILE [TYPE]

See also App::MatrixTool::Command::client::upload.


Paul Evans <>