Update documentation for version 2.0
This commit is contained in:
parent
959c3c9c9b
commit
107ec868ba
9 changed files with 204 additions and 181 deletions
5
Makefile
5
Makefile
|
|
@ -3,7 +3,8 @@ PREFIX = /usr/local
|
|||
MANPREFIX = ${PREFIX}/man
|
||||
|
||||
config:
|
||||
cp matrix-send.conf ~/.config/matrix-send.conf
|
||||
mkdir -p ~/.config/matrix-send
|
||||
cp config.lua ~/.config/matrix-send/config.lua
|
||||
|
||||
install:
|
||||
cp -f matrix-send ${DESTDIR}${PREFIX}/bin
|
||||
|
|
@ -11,4 +12,4 @@ install:
|
|||
mkdir -p ${DESTDIR}${MANPREFIX}/man1
|
||||
cp -f matrix-send.1 ${DESTDIR}${MANPREFIX}/man1
|
||||
mkdir -p ${DESTDIR}${MANPREFIX}/man5
|
||||
cp -f matrix-send.conf.5 ${DESTDIR}${MANPREFIX}/man5
|
||||
cp -f matrix-send-config.5 ${DESTDIR}${MANPREFIX}/man5
|
||||
|
|
|
|||
12
README.md
12
README.md
|
|
@ -1,22 +1,16 @@
|
|||
# matrix-send
|
||||
|
||||
A script that sends a message to a Matrix room.
|
||||
A script that sends messages to Matrix rooms.
|
||||
|
||||
[Read the manual page](https://jtbx.codeberg.page/man/matrix-send.1)
|
||||
|
||||
---
|
||||
|
||||
**Syntax:** `matrix-send message room`
|
||||
|
||||
**Example:** `matrix-send "Hello world\!" \!aBcDeFgHiJkLmNoP:example.org`
|
||||
|
||||
---
|
||||
|
||||
matrix-send is a simple script that sends a message to a Matrix room.
|
||||
|
||||
It does this by sending a JSON message to your Matrix server. The message types that are supported are *m.text*, and *m.notice*.
|
||||
It does this by sending a JSON message to your Matrix server. The message types that are supported are `m.text`, and `m.notice`.
|
||||
|
||||
It is mainly designed for automation. I use it on a private Matrix room of mine.
|
||||
It is mainly designed for automation.
|
||||
|
||||
There aren't any plans for matrix-send to support encryption.
|
||||
|
||||
|
|
|
|||
31
config.lua
Normal file
31
config.lua
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
login = {
|
||||
-- The Matrix server to use.
|
||||
server = "matrix-client.matrix.org", -- matrix.org
|
||||
|
||||
-- The user to log in to.
|
||||
username = "user",
|
||||
|
||||
-- The password for the user.
|
||||
password = "password",
|
||||
|
||||
-- The access token to use (instead of credentials).
|
||||
-- If token equals nil, credentials are used.
|
||||
-- If token is not nil, credentials are ignored.
|
||||
token = nil
|
||||
|
||||
-- The server value needs to be provided.
|
||||
-- You can choose to login with user credentials or a
|
||||
-- token. One of them needs to be provided.
|
||||
}
|
||||
|
||||
rooms = {
|
||||
-- Room aliases.
|
||||
-- Here you can add aliases for rooms,
|
||||
-- instead of having to type the confusing
|
||||
-- Room ID every single time you send a message.
|
||||
-- Examples:
|
||||
--my_alias = "!AbCdEfGhIjKl:burger.land",
|
||||
--lounge = "!MnOpQrSTuVWxYz:gaming.bruvs"
|
||||
-- When you want to send to a Matrix room, you
|
||||
-- can just type the alias instead of the long Room ID.
|
||||
}
|
||||
49
default_config.lua
Normal file
49
default_config.lua
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
-- The configuration file for matrix-send is written in Lua format.
|
||||
-- Here is a list of all possible options in the configuration file.
|
||||
-- Default values appear after the '=' sign.
|
||||
|
||||
login = {
|
||||
-- The Matrix server to use.
|
||||
server = nil,
|
||||
|
||||
-- The user to log in to.
|
||||
username = nil,
|
||||
|
||||
-- The password for the user.
|
||||
password = nil,
|
||||
|
||||
-- The access token to use (instead of credentials).
|
||||
-- If token equals nil, credentials are used.
|
||||
-- If token is not nil, credentials are ignored.
|
||||
token = nil
|
||||
|
||||
-- The server value needs to be provided.
|
||||
-- You can choose to login with user credentials or a
|
||||
-- token. One of them needs to be provided.
|
||||
}
|
||||
|
||||
cache = {
|
||||
-- The path to cache access tokens at.
|
||||
location = "~/.cache/matrix-send",
|
||||
|
||||
-- Disable caching access tokens?
|
||||
disable = false
|
||||
}
|
||||
|
||||
rooms = {
|
||||
-- Room aliases.
|
||||
-- Here you can add aliases for rooms,
|
||||
-- instead of having to type the confusing
|
||||
-- Room ID every single time you send a message.
|
||||
-- Examples:
|
||||
--my_alias = "!AbCdEfGhIjKl:burger.land",
|
||||
--lounge = "!MnOpQrSTuVWxYz:gaming.bruvs"
|
||||
-- When you want to send to a Matrix room, you
|
||||
-- can just type the alias instead of the long Room ID.
|
||||
}
|
||||
|
||||
advanced = {
|
||||
-- The default event type.
|
||||
-- Can be either m.text or m.notice.
|
||||
event = "m.text"
|
||||
}
|
||||
52
matrix-send
52
matrix-send
|
|
@ -104,58 +104,6 @@ function confpanic(s)
|
|||
os.exit(1)
|
||||
end
|
||||
|
||||
--[[
|
||||
The configuration file for matrix-send is written in Lua format.
|
||||
Here is a list of all possible options in the configuration file.
|
||||
Default values appear after the '=' sign.
|
||||
|
||||
login = {
|
||||
-- The Matrix server to use.
|
||||
server = nil,
|
||||
|
||||
-- The user to log in to.
|
||||
username = nil,
|
||||
|
||||
-- The password for the user.
|
||||
password = nil,
|
||||
|
||||
-- The access token to use (instead of credentials).
|
||||
-- If token equals nil, credentials are used.
|
||||
-- If token is not nil, credentials are ignored.
|
||||
token = nil
|
||||
|
||||
-- The server value needs to be provided.
|
||||
-- You can choose to login with user credentials or a
|
||||
-- token. One of them needs to be provided.
|
||||
}
|
||||
|
||||
cache = {
|
||||
-- The path to cache access tokens at.
|
||||
location = "~/.cache/matrix-send",
|
||||
|
||||
-- Disable caching access tokens?
|
||||
disable = false
|
||||
}
|
||||
|
||||
rooms = {
|
||||
-- Room aliases.
|
||||
-- Here you can add aliases for rooms,
|
||||
-- instead of having to type the confusing
|
||||
-- Room ID every single time you send a message.
|
||||
-- Examples:
|
||||
--my_alias = "!AbCdEfGhIjKl:burger.land",
|
||||
--lounge = "!MnOpQrSTuVWxYz:gaming.bruvs"
|
||||
-- When you want to send to a Matrix room, you
|
||||
-- can just type the alias instead of the long Room ID.
|
||||
}
|
||||
|
||||
advanced = {
|
||||
-- The default event type.
|
||||
-- Can be either m.text or m.notice.
|
||||
event = "m.text"
|
||||
}
|
||||
--]]
|
||||
|
||||
-- Default configuration file
|
||||
default_config = [[
|
||||
-- Default configuration file for matrix-send
|
||||
|
|
|
|||
65
matrix-send-config.5
Normal file
65
matrix-send-config.5
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
.Dd $Mdocdate: January 1 2023 $
|
||||
.Dt MATRIX-SEND-CONFIG 5
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm config.lua
|
||||
.Nd configuration file for
|
||||
.Xr matrix-send 1
|
||||
.Sh DESCRIPTION
|
||||
.Xr matrix-send 1
|
||||
sends messages to Matrix rooms. In order to send a message however, it needs
|
||||
credentials for the account sending the message. These credentials are provided
|
||||
in the
|
||||
.Nm
|
||||
configuration file, as well as other options if you need them.
|
||||
.Pp
|
||||
The configuration file is in Lua format, meaning
|
||||
you can write whatever Lua code you wish inside.
|
||||
.Pp
|
||||
The following configuration options are available:
|
||||
.Bl -tag -width 11n
|
||||
.Bl -tag -width login.server
|
||||
.It Ic login.server Ar server
|
||||
The Client-Server API address of the Matrix server being used.
|
||||
.It Ic login.username Ar username
|
||||
The username of the account being used.
|
||||
.It Ic login.password Ar password
|
||||
The password for the account being used.
|
||||
.It Ic login.token Ar token
|
||||
Instead of authenticating via username and password to obtain an access token, use
|
||||
.Ar token
|
||||
as the access token.
|
||||
.It Ic cache.location Ar location
|
||||
Use
|
||||
.Ar location
|
||||
as the cache location.
|
||||
.It Ic cache.disable
|
||||
Don't cache anything.
|
||||
.It Ic advanced.event Ar type
|
||||
Modify the default event type from the default (m.text) to
|
||||
.Ar type .
|
||||
Supported types are m.text, and m.notice.
|
||||
.El
|
||||
.Sh FILES
|
||||
.Bl -tag -width ~/.config/matrix-send/config.lua -compact
|
||||
.It Pa ~/.config/matrix-send/config.lua
|
||||
.Xr matrix-send 1
|
||||
configuration file
|
||||
.It Pa ~/.cache/matrix-send
|
||||
default cache directory
|
||||
.El
|
||||
.Sh EXAMPLES
|
||||
The following example logs into the user 'john' of the server
|
||||
matrix-client.matrix.org, and the password 'supersecretpassword',
|
||||
and sets the default event type to m.notice.
|
||||
.Bd -literal -offset indent
|
||||
login = {
|
||||
server = "matrix-client.matrix.org",
|
||||
username = "john",
|
||||
password = "supersecretpassword"
|
||||
}
|
||||
|
||||
advanced.event = "m.notice"
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr matrix-send 1
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,17 +0,0 @@
|
|||
## Example basic configuration for matrix-send
|
||||
# A line with an option (e.g. 'Username jeremy') is a "directive".
|
||||
# A line with only one word (e.g. 'NoCache') is a "statement".
|
||||
# Comments start with a pound (#)
|
||||
# Additional options can be found in matrix-send.conf(5)
|
||||
|
||||
# The Server directive is for your server's Matrix Client-Server API URL.
|
||||
# matrix-send assumes that this is valid.
|
||||
# matrix.org's CS API URL is matrix-client.matrix.org.
|
||||
# You can find it by typing it into Element's sign in page and hovering your mouse over it.
|
||||
Server matrix.envs.net
|
||||
|
||||
# The Username directive is your username for that server.
|
||||
Username john
|
||||
|
||||
# The Password directive is your password for your account.
|
||||
Password supersecretpassword
|
||||
|
|
@ -1,60 +0,0 @@
|
|||
.Dd $Mdocdate: August 4 2022 $
|
||||
.Dt MATRIX-SEND.CONF 5
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm matrix-send.conf
|
||||
.Nd configuration file for
|
||||
.Xr matrix-send 1
|
||||
.Sh DESCRIPTION
|
||||
.Xr matrix-send 1
|
||||
sends messages to Matrix rooms. In order to send a message however, it needs
|
||||
credentials for the account sending the message. These credentials are provided
|
||||
in the
|
||||
.Nm
|
||||
configuration file, as well as other options if you need them.
|
||||
.Pp
|
||||
The following configuration options are available:
|
||||
.Bl -tag -width 11n
|
||||
.Bl -tag -width keepenv
|
||||
.It Ic Server Ar server
|
||||
The Client-Server API address of the Matrix server being used.
|
||||
.It Ic Username Ar username
|
||||
The username of the account being used.
|
||||
.It Ic Password Ar password
|
||||
The password for the account being used.
|
||||
.It Ic AccessToken Ar token
|
||||
Instead of authenticating via username and password to obtain an access token, use
|
||||
.Ar token
|
||||
as the access token.
|
||||
.It Ic CacheLocation Ar location
|
||||
Modify the cache location from the default (~/.cache) to
|
||||
.Ar location .
|
||||
.It Ic NoCache
|
||||
Don't cache access tokens.
|
||||
.It Ic DefaultEvent Ar type
|
||||
Modify the default event type from the default (m.text) to
|
||||
.Ar type .
|
||||
Supported types are m.text, and m.notice.
|
||||
.It Ic PrettyPrint
|
||||
Pretty-print the JSON server messages.
|
||||
.El
|
||||
.Sh FILES
|
||||
.Bl -tag -width ~/.config/matrix-send.conf -compact
|
||||
.It Pa ~/.config/matrix-send.conf
|
||||
.Xr matrix-send 1
|
||||
configuration file.
|
||||
.It Pa ~/.cache
|
||||
Default cache location.
|
||||
.El
|
||||
.Sh EXAMPLES
|
||||
The following example logs into the user johndoe of the server with the
|
||||
Client-Server API address of matrix-client.matrix.org with the password
|
||||
supersecretpassword, and sets the default event type to m.notice.
|
||||
.Bd -literal -offset indent
|
||||
Server matrix-client.matrix.org
|
||||
Username johndoe
|
||||
Password supersecretpassword
|
||||
DefaultEvent m.notice
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr matrix-send 1
|
||||
Loading…
Add table
Add a link
Reference in a new issue