142 lines
3.7 KiB
Groff
142 lines
3.7 KiB
Groff
.Dd $Mdocdate: January 1 2023 $
|
|
.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 Ar config
|
|
.Op Fl CV
|
|
.Ar message room
|
|
.Ek
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
sends messages to Matrix rooms.
|
|
The default event type is m.text (standard text message),
|
|
but you can specify a custom type with
|
|
.Em -t .
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width keyword
|
|
.It Fl C
|
|
Clear cached access tokens and transaction IDs then exit.
|
|
.It Fl c Ar config
|
|
Instead of reading the default configuration file (~/.config/matrix-send.conf), read
|
|
.Ar config .
|
|
.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 V
|
|
Print version information and exit.
|
|
.El
|
|
.Pp
|
|
To begin, start by making a configuration file. This always has the location of
|
|
.Em ~/.config/matrix-send/config.lua .
|
|
|
|
At the very least, your configuration file has to contain three values:
|
|
.Em login.server ,
|
|
.Em login.username ,
|
|
and
|
|
.Em login.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
|
|
login = {
|
|
server = "matrix.envs.net",
|
|
username = "john",
|
|
password = "supersecretpassword"
|
|
}
|
|
.Ed
|
|
.Pp
|
|
It could also look like this:
|
|
.Bd -literal -offset indent
|
|
login.server = "matrix.envs.net"
|
|
login.username = "john"
|
|
login.password = "supersecretpassword"
|
|
.Ed
|
|
.Pp
|
|
In those examples, 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 this address 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 should already have it.
|
|
.Pp
|
|
You may have noticed that with this configuration, your password
|
|
is visible in plain sight.
|
|
|
|
If you would like to have to encrypt your password before use,
|
|
you could
|
|
replace the
|
|
.Em login.password
|
|
line with something similar to this
|
|
.Pp
|
|
login.password = sh "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-config 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/token .
|
|
If you would like to disable caching of access tokens, add
|
|
.Pp
|
|
.Dl cache.disable = true
|
|
.Pp
|
|
to your
|
|
.Em config.lua .
|
|
.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/config.lua
|
|
.It Pa ~/.config/matrix-send/config.lua
|
|
configuration file for
|
|
.Nm
|
|
.It Pa ~/.cache/matrix-send
|
|
cache directory
|
|
.El
|
|
|
|
.Sh EXAMPLES
|
|
Send a message saying "Hello world!" to the Matrix room !TfbDbeqp:example.org:
|
|
.Pp
|
|
.Dl matrix-send 'Hello world!' \\!TfbDbeqp:example.org
|
|
.Pp
|
|
|
|
.Sh SEE ALSO
|
|
.Xr matrix-send-config 5
|