"matrix-cli" is a tool developed by Wizardry and Steamworks that facilitates the interaction with Matrix.org servers by implementing the Matrix.org protocol using the official Matrix.org JavaScript SDK (matrix-js-sdk). Initially the tool was conceived as a tool for the explicit purpose of pushing announcements to the Wizardry and Steamworks Matrix.org space but has evolved to include more useful commands for a more general usage patterns.

As implemented, so far:

• sending a message to a room,
• joining rooms,
• parting rooms,
• listing available rooms,
• logging-in via username and password,
• support for any Matrix.org server, including self-hosted,
• the ability to process HTML-rich messages, including embedded images with the HTML <img> tag,
• uploading files in bulk and posting them

First ensure that node.js and npm are installed and then execute:

npm install -g matrix-cli --registry https://npm.grimore.org

that will install matrix-cli such that the matrix-cli tool can be called from the command line.

The sources can also be checked out via Subversion by using the URL:

• https://svn.grimore.org/matrix-cli

For instance, via the command:

svn co https://svn.grimore.org/matrix-cli

After that, the requirements must be pulled, such that the following command:

npm install

must be ran inside the matrix-cli folder checked out from the SVN repository.

matrix-cli should be very easy to use and benefits from an exhaustive contextual help system. For instance, running the matrix-cli command in a terminal will output:

$ ./matrix-cli.js 
Usage: matrix-cli [options] [command]
 
+--       --+
|   /\ /\   | matrix.org command-line client
|  +  +  +  |    (c) 2024 Wizardry and Steamworks
+--       --+
 
Options:
  -V, --version                       output the version number
  -h, --help                          display help for command
 
Commands:
  say [options] <room> <text>         send a message to a room
  publish [options] <room> <file...>  publish files to a room from either the
                                      local filesystem or from an URL
  join [options] <room>               join a room
  part [options] <room>               part with a room
  list [options]                      list various matrix entities
  help [command]                      display help for command

and more help for each command can be requested by running, for example:

$ ./matrix-cli.js say --help
Usage: matrix-cli say [options] <room> <text>
 
send a message to a room
 
Options:
  -u, --user <user>          the username to log-in to matrix.org
  -p, --password <password>  the password to log-in to matrix.org
  -s, --server <server>      the server to log-in to
  -t, --type <type>          the message format; either text (default) or html
  -h, --help                 display help for command

matrix-cli.js is meant to be a oneshot command, such that authentication will have to be performed every time a command is issued. For example, in order to message the room "Announcements" with the text "hello world!" the following command will be issued:

$ ./matrix-cli.js say -u wizardry.steamworks -s https://matrix.grimore.org Announcements "hello world!"
info: No password provided, reading password from command line.
prompt: Enter the password (will not be echoed): : 
info: Logged in.
info: Client synchronizing...
info: Synchronized.
info: Message sent to room Announcements.

Note that the password option -p has been omitted such that matrix-cli has requested the password on the command line - this holds for all commands; if the password option is omitted, matrix-cli will prompt for a password.

After a command is executed, matrix-cli takes care to log out gracefully and return the terminal to the user.

This section covers some of the more advanced usages of matrix-cli.

matrix-cli is capable of processing HTML-enriched text messages and then post them in a room such that they display properly. For example, the matrix-cli invocation will post a message that contains some text, some bold text and two embedded images:

$ ./matrix-cli.js say -t html -u crafting -s https://matrix.grimore.org Announcements '<img src="https://slm-assets.secondlife.com/assets/26757434/lightbox/scifi12alienavatar_009.jpg?1593595106"></img><b>test</b> test <img src="https://slm-assets.secondlife.com/assets/30025825/lightbox/screenshot.jpg"></img>'

Here is what the message looks like on matrix, with the two embedded images:

The publish matrix-cli command can bulk-upload files to matrix. For example, the call:

$ ./matrix-cli.js publish -u crafting -s https://matrix.grimore.org Announcements ./aaaa.txt https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png https://w.wallhaven.cc/full/85/wallhaven-856dlk.png

will upload:

• the local file ./aaaa.txt,
• the file at the URL: https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png
• the file at he URL: https://w.wallhaven.cc/full/85/wallhaven-856dlk.png

to the matrix server.

The matrix-cli.js file contains a shebang at the top of the file:

#!/usr/bin/env node

that would allow users to execute the matrix-cli.js file as if it were an executable.

Obviously, this requires the env utility to be in /usr/bin and the node.js binary to be named "node" (note that on some distributions, the node.js binary is named nodejs instead).

In order to trivially avoid all problems, "matrix-cli.js" can be run prefixed by "node":

$ ./matrix-cli.js say -u wi...

Another issue that might be encountered under Cygwin is that the password prompt might not work, or will behave erratically, and this issue can be solved by using a software package called "winpty".