.Dd $Mdocdate: August 2 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 t Ar type
.Op Fl c
.Op Fl h
.Op Fl V
.Ar message room
.Ek
.Sh DESCRIPTION
.Nm
is a script that sends a message to a Matrix room.
It works by sending a JSON message to your Matrix server. The default message
type is m.text, but you can specify a custom type with
.Em -t .
.Pp
The options are as follows:
.Bl -tag -width keyword
.It Fl t Ar type
Change the event type to
.Ar type .
Currently supported types are
.Em m.text
and
.Em m.notice .
Default is
.Em m.text .
.It Fl c
Clear cached access tokens.
.It Fl h
Show the 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
.Pp
.Dl Password $(gpg -d /path/to/passwd.gpg)
.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:
.Pp
.Dl matrix-send "Hello world!" \\!zyxwvutsrq:example.org
.Pp
That would 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 EXAMPLES
Send a message saying "How are you?" to the Matrix room !TfbDbeqp:example.org:
.Pp
.Dl matrix-send 'How are you?' !TfbDbeqp:example.org
.Pp

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