128 lines
3.4 KiB
Groff
128 lines
3.4 KiB
Groff
.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
|