jeremy/matrix-send
1
Fork 0
Code Releases Activity

Update documentation for version 2.0

Browse source
This commit is contained in:
Jeremy 2023-01-01 12:03:47 +13:00
parent 88e373a777
commit a112ef195a
9 changed files with 204 additions and 181 deletions
Download patch file Download diff file Expand all files Collapse all files

94
matrix-send.1
View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: August 4 2022 $
.Dd $Mdocdate: January 1 2023 $
.Dt MATRIX-SEND 1
.Os
.Sh NAME
@ -8,19 +8,24 @@
.Nm matrix-send
.Bk -words
.Op Fl t Ar type
.Op Fl C Ar config
.Op Fl chV
.Op Fl c Ar config
.Op Fl CV
.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
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 .
@ -30,49 +35,52 @@ and
.Em m.notice .
Default is
.Em m.text .
.It Fl C Ar config
Instead of reading the default configuration file (~/.config/matrix-send.conf), read
.Ar config .
.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.
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.conf .
.Em ~/.config/matrix-send/config.lua .
At the very least, your configuration file has to contain 3 directives:
.Em Server ,
.Em Username ,
At the very least, your configuration file has to contain three values:
.Em login.server ,
.Em login.username ,
and
.Em Password .
Let's say your Matrix server is envs.net. Your username is john, and your password
.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
Server matrix.envs.net
Username john
Password supersecretpassword
login = {
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
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 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
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've already got it.
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.
At its most basic, matrix-send.conf is a shell script. This means you could
If you would like to have to encrypt your password before use,
you could
replace the
.Em Password
.Em login.password
line with something similar to this
.Pp
.Dl Password $(gpg -d /path/to/passwd.gpg)
login.password = sh "gpg -d /path/to/passwd.gpg"
.Pp
where
.Em /path/to/passwd.gpg
@ -82,7 +90,7 @@ 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 .
.Xr matrix-send-config 5 .
.Pp
To use
.Nm ,
@ -102,9 +110,13 @@ to the room with the Room ID !zyxwvutsrq:example.org.
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 .
.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
@ -112,19 +124,19 @@ There are currently no plans to add encryption to
.El
.Sh FILES
.Bl -tag -width ~/.config/matrix-send.conf
.It Pa ~/.config/matrix-send.conf
.Bl -tag -width ~/.config/matrix-send/config.lua
.It Pa ~/.config/matrix-send/config.lua
configuration file for
.Nm
.It Pa ~/.cache/matrix-send/access-token
access token cache file
.It Pa ~/.cache/matrix-send
cache directory
.El
.Sh EXAMPLES
Send a message saying "How are you?" to the Matrix room !TfbDbeqp:example.org:
Send a message saying "Hello world!" to the Matrix room !TfbDbeqp:example.org:
.Pp
.Dl matrix-send 'How are you?' !TfbDbeqp:example.org
.Dl matrix-send 'Hello world!' \\!TfbDbeqp:example.org
.Pp
.Sh SEE ALSO
.Xr matrix-send.conf 5
.Xr matrix-send-config 5