From 107ec868ba71ac407d4570999e0ebbaeb139487a Mon Sep 17 00:00:00 2001 From: Jeremy Baxter Date: Sun, 1 Jan 2023 12:03:47 +1300 Subject: [PATCH] Update documentation for version 2.0 --- Makefile | 5 ++- README.md | 12 ++---- config.lua | 31 +++++++++++++++ default_config.lua | 49 +++++++++++++++++++++++ matrix-send | 52 ------------------------ matrix-send-config.5 | 65 ++++++++++++++++++++++++++++++ matrix-send.1 | 94 +++++++++++++++++++++++++------------------- matrix-send.conf | 17 -------- matrix-send.conf.5 | 60 ---------------------------- 9 files changed, 204 insertions(+), 181 deletions(-) create mode 100644 config.lua create mode 100644 default_config.lua create mode 100644 matrix-send-config.5 delete mode 100644 matrix-send.conf delete mode 100644 matrix-send.conf.5 diff --git a/Makefile b/Makefile index cf63374..cd74faf 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 3b5d4ec..a71f45c 100644 --- a/README.md +++ b/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. diff --git a/config.lua b/config.lua new file mode 100644 index 0000000..f271a49 --- /dev/null +++ b/config.lua @@ -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. +} diff --git a/default_config.lua b/default_config.lua new file mode 100644 index 0000000..76cd492 --- /dev/null +++ b/default_config.lua @@ -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" +} diff --git a/matrix-send b/matrix-send index 392e393..f042356 100755 --- a/matrix-send +++ b/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 diff --git a/matrix-send-config.5 b/matrix-send-config.5 new file mode 100644 index 0000000..b2c468c --- /dev/null +++ b/matrix-send-config.5 @@ -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 diff --git a/matrix-send.1 b/matrix-send.1 index bd4bc75..9b57606 100644 --- a/matrix-send.1 +++ b/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 diff --git a/matrix-send.conf b/matrix-send.conf deleted file mode 100644 index a7582ab..0000000 --- a/matrix-send.conf +++ /dev/null @@ -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 diff --git a/matrix-send.conf.5 b/matrix-send.conf.5 deleted file mode 100644 index 55a1c50..0000000 --- a/matrix-send.conf.5 +++ /dev/null @@ -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