MATRIX-SEND(1) - General Commands Manual

# NAME

**matrix-send** - send a message to a Matrix room

# SYNOPSIS

**matrix-send**
\[**-c**]
\[**-h**]
\[**-v**]
*message room*

# DESCRIPTION

**matrix-send**
is a script to send a message to a Matrix room.
It works by sending a JSON request to your Matrix server. The message
type will always be m.text, but other options may be considered in the
future.

To begin, start by making a configuration file. This always has the location of
*~/.config/matrix-send.conf*.

At the very least, your configuration file has to contain 3 directives:
*Server*,
*Username*,
and
*Password*.
Let's say your Matrix server is envs.net. Your username is john, and your password
is supersecretpassword. Your configuration could look like this:

	Server matrix.envs.net
	Username john
	Password supersecretpassword

In that example, we used matrix.envs.net instead of envs.net. This is because
matrix.envs.net is the address in which the Client-Server API is listening on.
You can find your server's Client-Server API URL in Element by entering in
your server into the Homeserver dialogue in the sign-in screen, then hovering
over it once entered. Your server's Client-Server API URL should appear once
you hover over it. If it doesn't appear, you've already got it.

You may have noticed that with this configuration, your password
is visible in plain sight.

At its most basic, matrix-send.conf is a shell script. This means you could
replace the
*Password*
line with something similar to this

	Password $(gpg -d /path/to/passwd.gpg)

where
*/path/to/passwd.gpg*
is a GPG-encrypted plain text file containing only your password.
This line would mean that you would be asked for the passphrase required to
decrypt your password file before authenticating. This way, your password
is not in plain text.

More information on configuration options can be found in
matrix-send.conf(5).

To use
**matrix-send**,
you will need to get the Room ID of the room you'd like to send to.
This will be something like
*!zyxwvutsrq:example.org*.

Type the Room ID as the argument after the message you wish to send.
You may have to escape the exclamation mark with a backslash. For example:

	matrix-send "Hello world!" zyxwvutsrq:example.org

That should send a message saying
*Hello world!*
to the room with the Room ID !zyxwvutsrq:example.org.

By default,
**matrix-send**
caches access tokens in
*$HOME/.cache/matrix-send/access-token*.
If you would like to disable caching of access tokens, add NoCache to your
*matrix-send.conf*.

# FILES

*~/.config/matrix-send.conf*

> configuration file for
> **matrix-send**

*~/.cache/matrix-send/access-token*

> access token cache file

# SEE ALSO

matrix-send.conf(5)

OpenBSD 7.1 - July 28, 2022