.Dd $Mdocdate: July 28 2022 $
.Dt MATRIX-SEND 1
.Os
.Sh NAME
.Nm matrix-send
.Nd send a message to a Matrix room
.Sh SYNOPSIS
.Nm matrix-send
.Bk -words
.Op Fl c
.Op Fl h
.Op Fl v
.Ar message room
.Ek
.Sh DESCRIPTION
.Nm
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.
.Pp
The options are as follows:
.Bl -tag -width keyword
.It Fl c
Clear cached access tokens.
.It Fl h
Show a help menu, then exit.
.It Fl V
Print version and program information, then exit
.El
.Pp
To begin, start by making a configuration file. This always has the location of
.Em ~/.config/matrix-send.conf .

At the very least, your configuration file has to contain 3 directives:
.Em Server ,
.Em Username ,
and
.Em 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:
.Bd -literal -offset indent
Server matrix.envs.net
Username john
Password supersecretpassword
.Ed
.Pp
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.
.Pp
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
.Em Password
line with something similar to this
.Bd -literal -offset indent
Password $(gpg -d /path/to/passwd.gpg)
.Ed
.Pp
where
.Em /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
.Xr matrix-send.conf 5 .
.Pp
To use
.Nm ,
you will need to get the Room ID of the room you'd like to send to.
This will be something like
.Em !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:
.Bd -literal -offset indent
matrix-send "Hello world!" \!zyxwvutsrq:example.org
.Ed
.Pp
That should send a message saying
.Em Hello world!
to the room with the Room ID !zyxwvutsrq:example.org.
.Pp
By default,
.Nm
caches access tokens in
.Em $HOME/.cache/matrix-send/access-token .
If you would like to disable caching of access tokens, add NoCache to your
.Em matrix-send.conf .
.Pp
Encryption is not supported. All messages will be sent unencrypted.
There are currently no plans to add encryption to
.Nm .
.El

.Sh FILES
.Bl -tag -width ~/.config/matrix-send.conf
.It Pa ~/.config/matrix-send.conf
configuration file for
.Nm
.It Pa ~/.cache/matrix-send/access-token
access token cache file
.El

.Sh SEE ALSO
.Xr matrix-send.conf 5