1189 lines
83 KiB
Plaintext
1189 lines
83 KiB
Plaintext
Welcome to matrix-commander, a Matrix CLI client. ─── On first run use --login
|
|
to log in, to authenticate. On second run we suggest to use --verify to get
|
|
verified. Verification is built-in which can be used to verify devices. On
|
|
further runs this program implements a simple Matrix CLI client that can send
|
|
messages, listen to messages, verify devices, etc. It can send one or multiple
|
|
message to one or multiple Matrix rooms and/or users. The text messages can be
|
|
of various formats such as "text", "html", "markdown" or "code". Images, audio,
|
|
arbitrary files, or events can be sent as well. For receiving there are three
|
|
main options: listen forever, listen once and quit, and get the last N messages
|
|
and quit. End-to-end encryption is enabled by default and cannot be turned off,
|
|
but it can be disabled for specific use cases. ─── Bundling several actions
|
|
together into a single call to matrix-commander is faster than calling matrix-
|
|
commander multiple times with only one action. If there are both 'set' and 'get'
|
|
actions present in the arguments, then the 'set' actions will be performed
|
|
before the 'get' actions. Then send actions and at the very end listen actions
|
|
will be performed. ─── For even more explications and examples also read the
|
|
documentation provided in the on-line Github README.md file or the README.md in
|
|
your local installation. ─── For less information just use --help instead of
|
|
--manual.
|
|
|
|
usage: matrix-commander [--usage] [-h] [--manual] [--readme] [-d]
|
|
[--log-level DEBUG|INFO|WARNING|ERROR|CRITICAL [DEBUG|INFO|WARNING|ERROR|CRITICAL ...]]
|
|
[--verbose] [--login PASSWORD|SSO] [--verify [EMOJI]]
|
|
[--logout ME|ALL] [-c CREDENTIALS_FILE]
|
|
[-s STORE_DIRECTORY] [-r ROOM [ROOM ...]]
|
|
[--room-default DEFAULT_ROOM]
|
|
[--room-create ROOM_ALIAS [ROOM_ALIAS ...]]
|
|
[--room-dm-create USER [USER ...]]
|
|
[--room-dm-create-allow-duplicates]
|
|
[--room-join ROOM [ROOM ...]]
|
|
[--room-leave ROOM [ROOM ...]]
|
|
[--room-forget ROOM [ROOM ...]]
|
|
[--room-invite ROOM [ROOM ...]]
|
|
[--room-ban ROOM [ROOM ...]]
|
|
[--room-unban ROOM [ROOM ...]]
|
|
[--room-kick ROOM [ROOM ...]] [-u USER [USER ...]]
|
|
[--user-login USER] [--name ROOM_NAME [ROOM_NAME ...]]
|
|
[--topic ROOM_TOPIC [ROOM_TOPIC ...]]
|
|
[--alias ROOM_ALIAS [ROOM_ALIAS ...]]
|
|
[-m TEXT [TEXT ...]] [-i IMAGE_FILE [IMAGE_FILE ...]]
|
|
[-a AUDIO_FILE [AUDIO_FILE ...]] [-f FILE [FILE ...]]
|
|
[-e MATRIX_JSON_OBJECT [MATRIX_JSON_OBJECT ...]] [-w]
|
|
[-z] [-k] [-j] [-p SEPARATOR] [--config CONFIG_FILE]
|
|
[--proxy PROXY] [-n] [--encrypted]
|
|
[-l [NEVER|ONCE|FOREVER|TAIL|ALL]] [-t [NUMBER]] [-y]
|
|
[--print-event-id]
|
|
[--download-media [DOWNLOAD_DIRECTORY]]
|
|
[--download-media-name SOURCE|CLEAN|EVENTID|TIME]
|
|
[--os-notify] [--set-device-name DEVICE_NAME]
|
|
[--set-display-name DISPLAY_NAME] [--get-display-name]
|
|
[--set-presence ONLINE|OFFLINE|UNAVAILABLE]
|
|
[--get-presence] [--upload FILE [FILE ...]]
|
|
[--download MXC_URI [MXC_URI ...]]
|
|
[--delete-mxc MXC_URI [MXC_URI ...]]
|
|
[--delete-mxc-before TIMESTAMP [TIMESTAMP ...]]
|
|
[--joined-rooms] [--joined-members ROOM [ROOM ...]]
|
|
[--joined-dm-rooms USER [USER ...]]
|
|
[--mxc-to-http MXC_URI [MXC_URI ...]] [--devices]
|
|
[--discovery-info] [--login-info]
|
|
[--content-repository-config]
|
|
[--rest REST_METHOD DATA URL [REST_METHOD DATA URL ...]]
|
|
[--set-avatar AVATAR_MXC_URI]
|
|
[--get-avatar [USER ...]] [--get-profile [USER ...]]
|
|
[--get-room-info [ROOM ...]] [--get-client-info]
|
|
[--has-permission ROOM BAN|INVITE|KICK|NOTIFICATIONS|REDACT|etc [ROOM BAN|INVITE|KICK|NOTIFICATIONS|REDACT|etc ...]]
|
|
[--import-keys FILE PASSPHRASE FILE PASSPHRASE]
|
|
[--export-keys FILE PASSPHRASE FILE PASSPHRASE]
|
|
[--room-set-alias ROOM_ALIAS ROOM [ROOM_ALIAS ROOM ...]]
|
|
[--room-resolve-alias ROOM_ALIAS [ROOM_ALIAS ...]]
|
|
[--room-delete-alias ROOM_ALIAS [ROOM_ALIAS ...]]
|
|
[--get-openid-token [USER ...]]
|
|
[--room-get-visibility [ROOM ...]]
|
|
[--room-get-state [ROOM ...]]
|
|
[--delete-device DEVICE [DEVICE ...]]
|
|
[--room-redact ROOM_ID EVENT_ID REASON [ROOM_ID EVENT_ID REASON ...]]
|
|
[--whoami] [--no-ssl]
|
|
[--ssl-certificate SSL_CERTIFICATE_FILE]
|
|
[--file-name FILE [FILE ...]]
|
|
[--key-dict KEY_DICTIONARY [KEY_DICTIONARY ...]]
|
|
[--plain] [--separator SEPARATOR]
|
|
[--access-token ACCESS_TOKEN] [--password PASSWORD]
|
|
[--homeserver HOMESERVER_URL] [--device DEVICE_NAME]
|
|
[--sync FULL|OFF] [-o TEXT|JSON|JSON-MAX|JSON-SPEC]
|
|
[--room-invites [LIST|JOIN|LIST+JOIN]]
|
|
[-v [PRINT|CHECK]]
|
|
|
|
Welcome to matrix-commander, a Matrix CLI client.
|
|
|
|
options:
|
|
--usage Print usage. Details:: See also --help for printing a
|
|
bit more and --manual for printing a lot more detailed
|
|
information.
|
|
-h, --help Print help. Details:: See also --usage for printing
|
|
even less information, and --manual for printing more
|
|
detailed information.
|
|
--manual Print manual. Details:: See also --usage for printing
|
|
the absolute minimum, and --help for printing less.
|
|
--readme Print README.md file. Details:: Tries to print the
|
|
local README.md file from installation. If not found
|
|
it will get the README.md file from github.com and
|
|
print it. See also --usage, --help, and --manual.
|
|
-d, --debug Print debug information. Details:: If used once, only
|
|
the log level of matrix-commander is set to DEBUG. If
|
|
used twice ("-d -d" or "-dd") then log levels of both
|
|
matrix-commander and underlying modules are set to
|
|
DEBUG. "-d" is a shortcut for "--log-level DEBUG". See
|
|
also --log-level. "-d" takes precedence over "--log-
|
|
level". Additionally, have a look also at the option "
|
|
--verbose".
|
|
--log-level DEBUG|INFO|WARNING|ERROR|CRITICAL [DEBUG|INFO|WARNING|ERROR|CRITICAL ...]
|
|
Set the log level(s). Details:: Possible values are
|
|
"DEBUG", "INFO", "WARNING", "ERROR", and "CRITICAL".
|
|
If --log_level is used with one level argument, only
|
|
the log level of matrix-commander is set to the
|
|
specified value. If --log_level is used with two level
|
|
argument (e.g. "--log-level WARNING ERROR") then log
|
|
levels of both matrix-commander and underlying modules
|
|
are set to the specified values. See also --debug.
|
|
--verbose Set the verbosity level. Details:: If not used, then
|
|
verbosity will be set to low. If used once, verbosity
|
|
will be high. If used more than once, verbosity will
|
|
be very high. Verbosity only affects the debug
|
|
information. So, if '--debug' is not used then '--
|
|
verbose' will be ignored.
|
|
--login PASSWORD|SSO Login to and authenticate with the Matrix homeserver.
|
|
Details:: This requires exactly one argument, the
|
|
login method. Currently two choices are offered:
|
|
'password' and 'sso'. Provide one of these methods. If
|
|
you have chosen 'password', you will authenticate
|
|
through your account password. You can optionally
|
|
provide these additional arguments: --homeserver to
|
|
specify the Matrix homeserver, --user-login to specify
|
|
the log in user id, --password to specify the
|
|
password, --device to specify a device name, --room-
|
|
default to specify a default room for
|
|
sending/listening. If you have chosen 'sso', you will
|
|
authenticate through Single Sign-On. A web-browser
|
|
will be started and you authenticate on the webpage.
|
|
You can optionally provide these additional arguments:
|
|
--homeserver to specify the Matrix homeserver, --user-
|
|
login to specify the log in user id, --device to
|
|
specify a device name, --room-default to specify a
|
|
default room for sending/listening. See all the extra
|
|
arguments for further explanations. ----- SSO (Single
|
|
Sign-On) starts a web browser and connects the user to
|
|
a web page on the server for login. SSO will only work
|
|
if the server supports it and if there is access to a
|
|
browser. So, don't use SSO on headless homeservers
|
|
where there is no browser installed or accessible.
|
|
--verify [EMOJI] Perform verification. Details:: By default, no
|
|
verification is performed. Possible values are:
|
|
"emoji", "emojireq",and "manual". If verification is
|
|
desired, run this program in the foreground (not as a
|
|
service) and without a pipe. While verification is
|
|
optional it is highly recommended, and it is
|
|
recommended to be done right after (or together with)
|
|
the --login action. Verification is always
|
|
interactive, i.e. it required keyboard input.
|
|
Verification questions will be printed on stdout and
|
|
the user has to respond via the keyboard to accept or
|
|
reject verification. Once verification is complete,
|
|
the program may be run as a service. Manual
|
|
verification requires you to specify a user with
|
|
--user and a device with --device. Manual verification
|
|
is a minimal one-way verification. In short, you are
|
|
trusting the device specified with --device, belonging
|
|
to user specified with --user, but that does not
|
|
enable this device to trust you back. It is a one-way
|
|
trust. For more info read: https://matrix-
|
|
nio.readthedocs.io/en/latest/examples.html#manual-
|
|
encryption-key-verification. Emoji verification is
|
|
best done as follows: The type 'emoji' waits for
|
|
someone else to send a verification request, which it
|
|
will then accept and go through the verification
|
|
process. Type 'emojireq' (proactively) sends a
|
|
verification request to a device specified with
|
|
--device belonging to a user specified with --user. It
|
|
then waits for the peer to accept the verification
|
|
request in order to inter into the verification
|
|
process. Different Matrix clients perfrom verification
|
|
differently and have different GUI elements. Find the
|
|
button that says 'Accept', 'Verify with another
|
|
device', 'Verify', 'Interactively verify by Emoji' or
|
|
similar. Once both accept emoji verification matrix-
|
|
commander will show a set of emoji icons and names in
|
|
the terminal. Compare them visually. Confirm on both
|
|
sides (Yes, They Match, Got it), finally click OK. You
|
|
should see a green shield and also see that the
|
|
matrix-commander device is now green and verified. In
|
|
the terminal you should see a text message indicating
|
|
success. Verification is done one device at a time.
|
|
Currently for known reasons the verification feature
|
|
is partially broken. Read the issue on Github for more
|
|
details.
|
|
--logout ME|ALL Logout. Details:: Logout this or all devices from the
|
|
Matrix homeserver. This requires exactly one argument.
|
|
Two choices are offered: 'me' and 'all'. Provide one
|
|
of these choices. If you choose 'me', only the one
|
|
device matrix-commander is currently using will be
|
|
logged out. If you choose 'all', all devices of the
|
|
user used by matrix-commander will be logged out.
|
|
While --logout neither removes the credentials nor the
|
|
store, the logout action removes the device and makes
|
|
the access-token stored in the credentials invalid.
|
|
Hence, after a --logout, one must manually remove
|
|
credentials and store, and then perform a new --login
|
|
to use matrix-commander again. You can perfectly use
|
|
matrix-commander without ever logging out. --logout is
|
|
a cleanup if you have decided not to use this (or all)
|
|
device(s) ever again.
|
|
-c CREDENTIALS_FILE, --credentials CREDENTIALS_FILE
|
|
Specify location of credentials file. Details:: On
|
|
first run, information about homeserver, user, room
|
|
id, etc. will be written to a credentials file. By
|
|
default, this file is "credentials.json". On further
|
|
runs the credentials file is read to permit logging
|
|
into the correct Matrix account and sending messages
|
|
to the preconfigured room. If this option is provided,
|
|
the provided file name will be used as credentials
|
|
file instead of the default one.
|
|
-s STORE_DIRECTORY, --store STORE_DIRECTORY
|
|
Specify location of store directory. Details:: Path to
|
|
directory to be used as "store" for encrypted
|
|
messaging. By default, this directory is "./store/".
|
|
Since encryption is always enabled, a store is always
|
|
needed. The provided directory name will be used as
|
|
persistent storage directory instead of the default
|
|
one. Preferably, for multiple executions of this
|
|
program use the same store for the same device. The
|
|
store directory can be shared between multiple
|
|
different devices and users.
|
|
-r ROOM [ROOM ...], --room ROOM [ROOM ...]
|
|
Specify one or multiple rooms. Details:: Optionally
|
|
specify one or multiple rooms via room ids or room
|
|
aliases. --room is used by various send actions and
|
|
various listen actions. The default room is provided
|
|
in the credentials file (specified at --login with
|
|
--room-default). If a room (or multiple ones) is (or
|
|
are) provided in the --room arguments, then it (or
|
|
they) will be used instead of the one from the
|
|
credentials file. The user must have access to the
|
|
specified room in order to send messages there or
|
|
listen on the room. Messages cannot be sent to
|
|
arbitrary rooms. When specifying the room id some
|
|
shells require the exclamation mark to be escaped with
|
|
a backslash. As an alternative to specifying a room as
|
|
destination, one can specify a user as a destination
|
|
with the '--user' argument. See '--user' and the term
|
|
'DM (direct messaging)' for details. Specifying a room
|
|
is always faster and more efficient than specifying a
|
|
user. Not all listen operations allow setting a room.
|
|
Read more under the --listen options and similar. Most
|
|
actions also support room aliases instead of room ids.
|
|
Some even short room aliases.
|
|
--room-default DEFAULT_ROOM
|
|
Specify the default room at --login. Details::
|
|
Optionally specify a room as the default room for
|
|
future actions. If not specified for --login, it will
|
|
be queried via the keyboard. --login stores the
|
|
specified room as default room in your credentials
|
|
file. This option is only used in combination with
|
|
--login. A default room is needed. Specify a valid
|
|
room either with --room-default or provide it via
|
|
keyboard.
|
|
--room-create ROOM_ALIAS [ROOM_ALIAS ...]
|
|
Create one or multiple rooms for given alias(es).
|
|
Details:: One or multiple room aliases can be
|
|
specified. For each alias specified a room will be
|
|
created. For each created room one line with room id
|
|
and alias will be printed to stdout. If you are not
|
|
interested in an alias, provide an empty string like
|
|
"". The alias provided must be in canonical local
|
|
form, i.e. if you want a final full alias like
|
|
"#SomeRoomAlias:matrix.example.com" you must provide
|
|
the string 'SomeRoomAlias'. The user must be permitted
|
|
to create rooms. Combine --room-create with --name and
|
|
--topic to add names and topics to the room(s) to be
|
|
created. Rooms are by default created encrypted; to
|
|
overwrite that and to create a room with encryption
|
|
disabled use '--plain'. Room id, room alias,
|
|
encryption and other fields are printed as output, one
|
|
line per created room.
|
|
--room-dm-create USER [USER ...]
|
|
Create one or multiple DM rooms with the specified
|
|
users. Details:: For each user specified a DM room
|
|
will be created and the user invited to it. For each
|
|
created room one line with room id and alias will be
|
|
printed to stdout. The user must be permitted to
|
|
create rooms. Combine --room-dm-create with --name,
|
|
--topic, --alias to add names, topics and aliases to
|
|
the room(s) to be created. DM rooms are by default
|
|
created encrypted; to overwrite that and to create a
|
|
room with encryption disabled use '--plain'. See
|
|
option '--room-dm-create-allow-duplicates'. If not
|
|
used, then an invitation-accepted DM room is searched.
|
|
If an existing DM room is found, no new DM room will
|
|
be created. If currently no invitation-accepted DM
|
|
room exists or --room-dm-create-allow-duplicates is
|
|
used, then a new DM will be created. Note, that one
|
|
can create/have any number of DM rooms with the same
|
|
person. Room id, room alias, encryption and other
|
|
fields are printed as output, one line per created
|
|
room. If a room is not created because one already
|
|
exists, then the room id of the first DM room found is
|
|
printed, but neither the alias nor other fields.
|
|
--room-dm-create-allow-duplicates
|
|
Allow creating duplicate DM rooms. Details:: By
|
|
default, if this option is bot used duplicates are
|
|
avoided. Actions that support this option are: --room-
|
|
dm-create. To overwrite that default and to allow the
|
|
creation of a DM room even if a DM room already
|
|
exists, use '--room-dm-create-allow-duplicates'. See
|
|
the --room-dm-create commands.
|
|
--room-join ROOM [ROOM ...]
|
|
Join one room or multiple rooms. Details:: One or
|
|
multiple room aliases can be specified. The room (or
|
|
multiple ones) provided in the arguments will be
|
|
joined. The user must have permissions to join these
|
|
rooms.
|
|
--room-leave ROOM [ROOM ...]
|
|
Leave one room or multiple rooms. Details:: One or
|
|
multiple room aliases can be specified. The room (or
|
|
multiple ones) provided in the arguments will be left.
|
|
--room-forget ROOM [ROOM ...]
|
|
Forget one room or multiple rooms. Details:: After
|
|
leaving a room you should (most likely) forget the
|
|
room. Forgetting a room removes the users' room
|
|
history. One or multiple room aliases can be
|
|
specified. The room (or multiple ones) provided in the
|
|
arguments will be forgotten. If all users forget a
|
|
room, the room can eventually be deleted on the
|
|
server.
|
|
--room-invite ROOM [ROOM ...]
|
|
Invite one ore more users to join one or more rooms.
|
|
Details:: Specify the user(s) as arguments to --user.
|
|
Specify the rooms as arguments to this option, i.e. as
|
|
arguments to --room-invite. The user must have
|
|
permissions to invite users. Don't confuse this option
|
|
with --room-invites.
|
|
--room-ban ROOM [ROOM ...]
|
|
Ban one ore more users from one or more rooms.
|
|
Details:: Specify the user(s) as arguments to --user.
|
|
Specify the rooms as arguments to this option, i.e. as
|
|
arguments to --room-ban. The user must have
|
|
permissions to ban users.
|
|
--room-unban ROOM [ROOM ...]
|
|
Unban one ore more users from one or more rooms.
|
|
Details:: Specify the user(s) as arguments to --user.
|
|
Specify the rooms as arguments to this option, i.e. as
|
|
arguments to --room-unban. The user must have
|
|
permissions to unban users.
|
|
--room-kick ROOM [ROOM ...]
|
|
Kick one ore more users from one or more rooms.
|
|
Details:: Specify the user(s) as arguments to --user.
|
|
Specify the rooms as arguments to this option, i.e. as
|
|
arguments to --room-kick. The user must have
|
|
permissions to kick users.
|
|
-u USER [USER ...], --user USER [USER ...]
|
|
Specify one or multiple users. Details:: This option
|
|
is meaningful in combination with a) room actions like
|
|
--room-invite, --room-ban, --room-unban, etc. and b)
|
|
send actions like -m, -i, -f, etc. c) some listen
|
|
actions --listen, as well as d) actions like --delete-
|
|
device and e) --verify manual, --verify emojireq. In
|
|
case of a) this option --user specifies the users to
|
|
be used with room commands (like invite, ban, etc.).
|
|
In case of b) the option --user can be used as an
|
|
alternative to specifying a room as destination for
|
|
text (-m), images (-i), etc. For send actions '--user'
|
|
is providing the functionality of 'DM (direct
|
|
messaging)'. For c) this option allows an alternative
|
|
to specifying a room as destination for some --listen
|
|
actions. For d) this gives the option to delete the
|
|
device of a different user. ----- What is a DM?
|
|
matrix-commander tries to find a room that contains
|
|
only the sender and the receiver, hence DM. These
|
|
rooms have nothing special other the fact that they
|
|
only have 2 members and them being the sender and
|
|
recipient respectively. If such a room is found, the
|
|
first one found will be used as destination. If no
|
|
such room is found, the send fails and the user should
|
|
do a --room-create and --room-invite first. If
|
|
multiple such rooms exist, one of them will be used
|
|
(arbitrarily). For sending and listening, specifying a
|
|
room directly is always faster and more efficient than
|
|
specifying a user. So, if you know the room, it is
|
|
preferred to use --room instead of --user. For b) and
|
|
c) --user can be specified in 3 ways: 1) full user id
|
|
as in '@john:example.org', 2) partial user id as in
|
|
'@john' when the user is on the same homeserver
|
|
(example.org will be automatically appended), or 3) a
|
|
display name as in 'john'. Be careful, when using
|
|
display names as they might not be unique, and you
|
|
could be sending to the wrong person. To see possible
|
|
display names use the --joined-members '*' option
|
|
which will show you the display names in the middle
|
|
column.
|
|
--user-login USER Specify user for --login. Details:: Optional argument
|
|
to specify the user for --login. This gives the option
|
|
to specify the user id for login. For '--login sso'
|
|
the --user-login is not needed as user id can be
|
|
obtained from server via SSO. For '--login password',
|
|
if not provided it will be queried via keyboard. A
|
|
full user id like '@john:example.com', a partial user
|
|
name like '@john', and a short user name like 'john'
|
|
can be given. --user-login is only used by --login and
|
|
ignored by all other actions.
|
|
--name ROOM_NAME [ROOM_NAME ...]
|
|
Specify one or multiple room names. Details:: This
|
|
option is only meaningful in combination with option
|
|
--room-create. This option --name specifies the names
|
|
to be used with the command --room-create.
|
|
--topic ROOM_TOPIC [ROOM_TOPIC ...]
|
|
Specify one or multiple room topics. Details:: This
|
|
option is only meaningful in combination with option
|
|
--room-create. This option --topic specifies the
|
|
topics to be used with the command --room-create.
|
|
--alias ROOM_ALIAS [ROOM_ALIAS ...]
|
|
Specify one or multiple room aliases. Details:: This
|
|
option is only meaningful in combination with option
|
|
--room-dm-create. This option --alias specifies the
|
|
aliases to be used with the command --room-dm-create.
|
|
-m TEXT [TEXT ...], --message TEXT [TEXT ...]
|
|
Send one or multiple text messages. Details:: Message
|
|
data must not be binary data, it must be text. If no
|
|
'-m' is used and no other conflicting arguments are
|
|
provided, and information is piped into the program,
|
|
then the piped data will be used as message. Finally,
|
|
if there are no operations at all in the arguments,
|
|
then a message will be read from stdin, i.e. from the
|
|
keyboard. This option can be used multiple times to
|
|
send multiple messages. If there is data piped into
|
|
this program, then first data from the pipe is
|
|
published, then messages from this option are
|
|
published. Messages will be sent last, i.e. after
|
|
objects like images, audio, files, events, etc. Input
|
|
piped via stdin can additionally be specified with the
|
|
special character '-'. If you want to feed a text
|
|
message into matrix-commander via a pipe, via stdin,
|
|
then specify the special character '-'. If '-' is
|
|
specified as message, then the program will read the
|
|
message from stdin. With '-' the whole message, all
|
|
lines, will be considered a single message and sent as
|
|
one message. If your message is literally '-' then use
|
|
'\-' as message in the argument. '-' may appear in any
|
|
position, i.e. '-m "start" - "end"' will send 3
|
|
messages out of which the second one is read from
|
|
stdin. '-' may appear only once overall in all
|
|
arguments. Similar to '-', another shortcut character
|
|
is '_'. The special character '_' is used for
|
|
streaming data via a pipe on stdin. With '_' the stdin
|
|
pipe is read line-by-line and each line is treated as
|
|
a separate message and sent right away. The program
|
|
waits for pipe input until the pipe is closed. E.g.
|
|
Imagine a tool that generates output sporadically
|
|
24x7. It can be piped, i.e. streamed, into matrix-
|
|
commander, and matrix-commander stays active, sending
|
|
all input instantly. If you want to send the literal
|
|
letter '_' then escape it and send '\_'. '_' can be
|
|
used only once. And either '-' or '_' can be used.
|
|
-i IMAGE_FILE [IMAGE_FILE ...], --image IMAGE_FILE [IMAGE_FILE ...]
|
|
Send one or multiple image files. Details:: This
|
|
option can be used multiple times to send multiple
|
|
images. First images are sent, then text messages are
|
|
sent. If you want to feed an image into matrix-
|
|
commander via a pipe, via stdin, then specify the
|
|
special character '-'. If '-' is specified as image
|
|
file name, then the program will read the image data
|
|
from stdin. If your image file is literally named '-'
|
|
then use '\-' as file name in the argument. '-' may
|
|
appear in any position, i.e. '-i image1.jpg -
|
|
image3.png' will send 3 images out of which the second
|
|
one is read from stdin. '-' may appear only once
|
|
overall in all arguments. If the file exists already,
|
|
it is more efficient to specify the file name than to
|
|
pipe the file through stdin.
|
|
-a AUDIO_FILE [AUDIO_FILE ...], --audio AUDIO_FILE [AUDIO_FILE ...]
|
|
Send one or multiple audio files. Details:: This
|
|
option can be used multiple times to send multiple
|
|
audio files. First audios are sent, then text messages
|
|
are sent. If you want to feed an audio into matrix-
|
|
commander via a pipe, via stdin, then specify the
|
|
special character '-'. See description of '-i' to see
|
|
how '-' is handled.
|
|
-f FILE [FILE ...], --file FILE [FILE ...]
|
|
Send one or multiple files (e.g. PDF, DOC, MP4).
|
|
Details:: This option can be used multiple times to
|
|
send multiple files. First files are sent, then text
|
|
messages are sent. If you want to feed a file into
|
|
matrix-commander via a pipe, via stdin, then specify
|
|
the special character '-'. See description of '-i' to
|
|
see how '-' is handled.
|
|
-e MATRIX_JSON_OBJECT [MATRIX_JSON_OBJECT ...], --event MATRIX_JSON_OBJECT [MATRIX_JSON_OBJECT ...]
|
|
Send a Matrix JSON event. Details:: Send an event that
|
|
is formatted as a JSON object as specified by the
|
|
Matrix protocol. This allows the advanced user to send
|
|
additional types of events such as reactions, send
|
|
replies to previous events, or edit previous messages.
|
|
Specifications for events can be found at
|
|
https://spec.matrix.org/unstable/proposals/. This
|
|
option can be used multiple times to send multiple
|
|
events. First events are sent, then text messages are
|
|
sent. If you want to feed an event into matrix-
|
|
commander via a pipe, via stdin, then specify the
|
|
special character '-'. See description of '-i' to see
|
|
how '-' is handled. See tests/test-event.sh for
|
|
examples.
|
|
-w, --html Send message as format "HTML". Details:: If not
|
|
specified, message will be sent as format "TEXT". E.g.
|
|
that allows some text to be bold, etc. Only a subset
|
|
of HTML tags are accepted by Matrix.
|
|
-z, --markdown Send message as format "MARKDOWN". Details:: If not
|
|
specified, message will be sent as format "TEXT". E.g.
|
|
that allows sending of text formatted in MarkDown
|
|
language.
|
|
-k, --code Send message as format "CODE". Details:: If not
|
|
specified, message will be sent as format "TEXT". If
|
|
both --html and --code are specified then --code takes
|
|
priority. This is useful for sending ASCII-art or
|
|
tabbed output like tables as a fixed-sized font will
|
|
be used for display.
|
|
-j, --emojize Send message after emojizing. Details:: If not
|
|
specified, message will be sent as format "TEXT". If
|
|
both --code and --emojize are specified then --code
|
|
takes priority. This is useful for sending emojis in
|
|
shortcode form :collision:.
|
|
-p SEPARATOR, --split SEPARATOR
|
|
Split message text into multiple Matrix messages.
|
|
Details:: If set, split the message(s) into multiple
|
|
messages wherever the string specified with --split
|
|
occurs. E.g. One pipes a stream of RSS articles into
|
|
the program and the articles are separated by three
|
|
newlines. Then with --split set to "\n\n\n" each
|
|
article will be printed in a separate message. By
|
|
default, i.e. if not set, no messages will be split.
|
|
--config CONFIG_FILE Specify the location of a config file. Details:: By
|
|
default, no config file is used. If this option is
|
|
provided, the provided file name will be used to read
|
|
configuration from. Not implemented.
|
|
--proxy PROXY Specify a proxy for connectivity. Details:: By
|
|
default, i.e. if this option is not set, no proxy is
|
|
used. If this option is used a proxy URL must be
|
|
provided. The provided proxy URL will be used for the
|
|
HTTP connection to the server. The proxy supports
|
|
SOCKS4(a), SOCKS5, and HTTP (tunneling). Examples of
|
|
valid URLs are "http://10.10.10.10:8118" or
|
|
"socks5://user:password@127.0.0.1:1080". URLs with
|
|
"https" or "socks4a" are not valid. Only "http",
|
|
"socks4" and "socks5" are valid.
|
|
-n, --notice Send message as notice. Details:: If not specified,
|
|
message will be sent as text.
|
|
--encrypted Send message end-to-end encrypted. Details::
|
|
Encryption is always turned on and will always be used
|
|
where possible. It cannot be turned off. This flag
|
|
does nothing as encryption is turned on with or
|
|
without this argument. This flag exists only for
|
|
historic reasons. In some specific case encryption can
|
|
be disabled, please see --plain.
|
|
-l [NEVER|ONCE|FOREVER|TAIL|ALL], --listen [NEVER|ONCE|FOREVER|TAIL|ALL]
|
|
Print received messages and listen to messages.
|
|
Details:: The --listen option takes one argument.
|
|
There are several choices: "never", "once", "forever",
|
|
"tail", and "all". By default, --listen is set to
|
|
"never". So, by default no listening will be done. Set
|
|
it to "forever" to listen for and print incoming
|
|
messages to stdout. "--listen forever" will listen to
|
|
all messages on all rooms forever. To stop listening
|
|
"forever", use Control-C on the keyboard or send a
|
|
signal to the process or service. The PID for
|
|
signaling can be found in a PID file in directory
|
|
"/home/user/.run". "--listen once" will get all the
|
|
messages from all rooms that are currently queued up.
|
|
So, with "once" the program will start, print waiting
|
|
messages (if any) and then stop. The timeout for
|
|
"once" is set to 10 seconds. So, be patient, it might
|
|
take up to that amount of time. "tail" reads and
|
|
prints the last N messages from the specified rooms,
|
|
then quits. The number N can be set with the --tail
|
|
option. With "tail" some messages read might be old,
|
|
i.e. already read before, some might be new, i.e.
|
|
never read before. It prints the messages and then the
|
|
program stops. Messages are sorted, last-first. Look
|
|
at --tail as that option is related to --listen tail.
|
|
The option "all" gets all messages available, old and
|
|
new. Unlike "once" and "forever" that listen in ALL
|
|
rooms, "tail" and "all" listen only to the room
|
|
specified in the credentials file or the --room
|
|
options.
|
|
-t [NUMBER], --tail [NUMBER]
|
|
Print last messages. Details:: The --tail option reads
|
|
and prints up to the last N messages from the
|
|
specified rooms, then quits. It takes one argument, an
|
|
integer, which we call N here. If there are fewer than
|
|
N messages in a room, it reads and prints up to N
|
|
messages. It gets the last N messages in reverse
|
|
order. It print the newest message first, and the
|
|
oldest message last. If --listen-self is not set it
|
|
will print less than N messages in many cases because
|
|
N messages are obtained, but some of them are
|
|
discarded by default if they are from the user itself.
|
|
Look at --listen as this option is related to --tail.
|
|
-y, --listen-self Print your own messages as well. Details:: If set and
|
|
listening, then program will listen to and print also
|
|
the messages sent by its own user. By default messages
|
|
from oneself are not printed.
|
|
--print-event-id Print event ids of received messages. Details:: If set
|
|
and listening, then 'matrix-commander' will print also
|
|
the event id for each received message or other
|
|
received event. If set and sending, then 'matrix-
|
|
commander' will print the event id of the sent message
|
|
or the sent object (audio, file, event) to stdout.
|
|
Other information like room id and reference to what
|
|
was sent will be printed too. For sending this is
|
|
useful, if after sending the user wishes to perform
|
|
further operations on the sent object, e.g.
|
|
redacting/deleting it after an expiration time, etc.
|
|
--download-media [DOWNLOAD_DIRECTORY]
|
|
Download media files while listening. Details:: If set
|
|
and listening, then program will download received
|
|
media files (e.g. image, audio, video, text, PDF
|
|
files). By default, media will be downloaded to this
|
|
directory: "./media/". You can overwrite default with
|
|
your preferred directory. If you provide a relative
|
|
path, the relative path will be relative to the local
|
|
directory. foo will become ./foo. foo/foo will become
|
|
./foo/foo and only works if ./foo already exists.
|
|
Absolute paths will remein unchanged. /tmp will remain
|
|
/tmp. /tmp/foo will be /tmp/foo. If media is encrypted
|
|
it will be decrypted and stored decrypted. By default
|
|
media files will not be downloaded.
|
|
--download-media-name SOURCE|CLEAN|EVENTID|TIME
|
|
Specify the method to derive the media filename.
|
|
Details:: This argument is optional. Currently four
|
|
choices are offered: 'source', 'clean', 'eventid', and
|
|
'time'. 'source' means the value specified by the
|
|
source (sender) will be used. If the sender, i.e.
|
|
source, specifies a value that is not a valid
|
|
filename, then a failure will occur and the media file
|
|
will not be saved. 'clean' means that all unusual
|
|
characters in the name provided by the source will be
|
|
replaced by an underscore to create a valid file name.
|
|
'eventid' means that the name provided by the source
|
|
will be ignored and the event-id will be used instead.
|
|
'time' means that the name provided by the source will
|
|
be ignored and the current time at the receiver will
|
|
be used instead. As an example, if the source/sender
|
|
provided 'image(1)!.jpg' as name for a given media
|
|
file then 'source' will store the media using filename
|
|
'image(1)!.jpg', 'clean' will store it as
|
|
'image_1__.jpg', 'eventid' as something like
|
|
'$rsad57dafs57asfag45gsFjdTXW1dsfroBiO2IsidKk', and
|
|
'time' as something like '20231012_152234_266600'
|
|
(YYYYMMDD_HHMMSS_MICROSECONDS). If not specified this
|
|
value defaults to 'clean'.
|
|
--os-notify Notify me of arriving messages. Details:: If set and
|
|
listening, then program will attempt to visually
|
|
notify of arriving messages through the operating
|
|
system. By default there is no notification via OS.
|
|
--set-device-name DEVICE_NAME
|
|
Set or rename the current device. Details:: Set or
|
|
rename the current device to the device name provided.
|
|
Send, listen and verify operations are allowed when
|
|
renaming the device.
|
|
--set-display-name DISPLAY_NAME
|
|
Set or rename the display name. Details:: Set or
|
|
rename the display name for the current user to the
|
|
display name provided. Send, listen and verify
|
|
operations are allowed when setting the display name.
|
|
Do not confuse this option with the option '--get-
|
|
room-info' which gets the room display name, not the
|
|
user display name.
|
|
--get-display-name Get the display name of yourself. Details:: Get the
|
|
display name of matrix-commander (itself), or of one
|
|
or multiple users. Specify user(s) with the --user
|
|
option. If no user is specified get the display name
|
|
of itself. Send, listen and verify operations are
|
|
allowed when getting display name(s). Do not confuse
|
|
this option with the option '--get-room-info' which
|
|
gets the room display name, not the user display name.
|
|
--set-presence ONLINE|OFFLINE|UNAVAILABLE
|
|
Set your presence. Details:: Set presence of matrix-
|
|
commander to the given value. Must be one of these
|
|
values: “online”, “offline”, “unavailable”. Otherwise
|
|
an error will be produced.
|
|
--get-presence Get your presence. Details:: Get presence of matrix-
|
|
commander (itself), or of one or multiple users.
|
|
Specify user(s) with the --user option. If no user is
|
|
specified get the presence of itself. Send, listen and
|
|
verify operations are allowed when getting
|
|
presence(s).
|
|
--upload FILE [FILE ...]
|
|
Upload one or multiple files to the content
|
|
repository. Details:: The files will be given a Matrix
|
|
URI and stored on the server. --upload allows the
|
|
optional argument --plain to skip encryption for
|
|
upload. See tests/test-upload.sh for an example.
|
|
--download MXC_URI [MXC_URI ...]
|
|
Download one or multiple files from the content
|
|
repository. Details:: You must provide one or multiple
|
|
Matrix URIs (MXCs) which are strings like this
|
|
'mxc://example.com/SomeStrangeUriKey'. If found they
|
|
will be downloaded, decrypted, and stored in local
|
|
files. If file names are specified with --file-name
|
|
the downloads will be saved with these file names. If
|
|
--file-name is not specified the original file name
|
|
from the upload will be used. If neither specified nor
|
|
available on server, then the file name of last resort
|
|
'mxc-<mxc-id>' will be used. If a file name in --file-
|
|
name contains the placeholder __mxc_id__, it will be
|
|
replaced with the mxc-id. If a file name is specified
|
|
as empty string in --file-name, then also the name
|
|
'mxc-<mxc-id>' will be used. By default, the upload
|
|
was encrypted so a decryption dictionary must be
|
|
provided to decrypt the data. Specify one or multiple
|
|
decryption keys with --key-dict. If --key-dict is not
|
|
set, not decryption is attempted; and the data might
|
|
be stored in encrypted fashion, or might be plain-text
|
|
if the --upload skipped encryption with --plain. See
|
|
tests/test-upload.sh for an example.
|
|
--delete-mxc MXC_URI [MXC_URI ...]
|
|
Delete one or multiple objects from the content
|
|
repository. Details:: You must provide one or multiple
|
|
Matrix URIs (MXC) which are strings like this
|
|
'mxc://example.com/SomeStrangeUriKey'. Alternatively,
|
|
you can just provide the MXC id, i.e. the part after
|
|
the last slash. If found they (i.e. the files they
|
|
represent) will be deleted from the server database.
|
|
In order to delete objects one must have server admin
|
|
permissions. Having only room admin permissions is not
|
|
sufficient and it will fail. Read https://matrix-org.g
|
|
ithub.io/synapse/latest/usage/administration/admin_api
|
|
/ for learning how to set server admin permissions on
|
|
the server. Alternatively, and optionally, one can
|
|
specify an access token which has server admin
|
|
permissions with the --access-token argument. See
|
|
tests/test-upload.sh for an example.
|
|
--delete-mxc-before TIMESTAMP [TIMESTAMP ...]
|
|
Delete old objects from the content
|
|
repositoryDetails:: Delete files from the content
|
|
repository that are older than a given timestamp. It
|
|
is the timestamp of last access, not the timestamp
|
|
when the file was created. Additionally you can
|
|
specify a size in bytes to indicate that only files
|
|
older than timestamp and larger than size will be
|
|
deleted. You must provide a timestamp of the following
|
|
format: 'DD.MM.YYYY HH:MM:SS' like '20.01.2022
|
|
19:38:42' for January 20, 2022, 7pm 38min 42sec. Files
|
|
that are still used in image data (e.g user profile,
|
|
room avatar) will not be deleted from the server
|
|
database. In order to delete objects one must have
|
|
server admin permissions. Having only room admin
|
|
permissions is not sufficient and it will fail. Read
|
|
https://matrix-org.github.io/synapse/latest/usage/admi
|
|
nistration/admin_api/ for learning how to set server
|
|
admin permissions on the server. Alternatively, and
|
|
optionally, one can specify an access token which has
|
|
server admin permissions with the --access-token
|
|
argument. See tests/test-upload.sh for an example.
|
|
--joined-rooms Print the list of joined rooms. Details:: All rooms
|
|
that you are a member of will be printed, one room per
|
|
line.
|
|
--joined-members ROOM [ROOM ...]
|
|
Print the list of joined members for one or multiple
|
|
rooms. Details:: If you want to print the joined
|
|
members of all rooms that you are member of, then use
|
|
the special character '*'.
|
|
--joined-dm-rooms USER [USER ...]
|
|
Print the list of joined DM rooms for one or multiple
|
|
users. Details:: For each user specified, it prints
|
|
all DM rooms that you share with the specified user.
|
|
There might be 0, 1, or multiple DM rooms for a given
|
|
user. Short user names like 'john' can be also be
|
|
given. If you want to print all DM rooms that you are
|
|
member of, then use the special character '*'. For
|
|
each DM room found a single line of output is printed.
|
|
--mxc-to-http MXC_URI [MXC_URI ...]
|
|
Convert MXC URIs to HTTP URLs. Details:: Convert one
|
|
or more matrix content URIs to the corresponding HTTP
|
|
URLs. The MXC URIs to provide look something like this
|
|
'mxc://example.com/SomeStrangeUriKey'. See tests/test-
|
|
upload.sh for an example.
|
|
--devices, --get-devices
|
|
Print the list of devices. Details:: All device of
|
|
this account will be printed, one device per line.
|
|
--discovery-info Print discovery information about current homeserver.
|
|
Details:: Note that not all homeservers support
|
|
discovery and an error might be reported.
|
|
--login-info Print login methods supported by the homeserver.
|
|
Details:: It prints one login method per line.
|
|
--content-repository-config
|
|
Print the content repository configuration. Details::
|
|
This currently just prints the upload size limit in
|
|
bytes.
|
|
--rest REST_METHOD DATA URL [REST_METHOD DATA URL ...]
|
|
Use the Matrix Client REST API. Details:: Matrix has
|
|
several extensive REST APIs. With the --rest argument
|
|
you can invoke a Matrix REST API call. This allows the
|
|
user to do pretty much anything, at the price of not
|
|
being very convenient. The APIs are described in
|
|
https://matrix.org/docs/api/,
|
|
https://spec.matrix.org/latest/client-server-api/,
|
|
https://matrix-org.github.io/synapse/latest/usage/admi
|
|
nistration/admin_api/, etc. Each REST call requires
|
|
exactly 3 arguments. So, the total number of arguments
|
|
used with --rest must be a multiple of 3. The argument
|
|
triples are: (a) the method, a string of GET, POST,
|
|
PUT, DELETE, or OPTIONS. (b) a string containing the
|
|
data (if any) in JSON format. (c) a string containing
|
|
the URL. All strings must be UTF-8. There are a few
|
|
placeholders. They are: __homeserver__ (like
|
|
https://matrix.example.org), __hostname__ (like
|
|
matrix.example.org), __access_token__, __user_id__
|
|
(like @mc:matrix.example.com), __device_id__, and
|
|
__room_id__. If a placeholder is found it is replaced
|
|
with the value from the local credentials file. An
|
|
example would be: --rest 'GET' ''
|
|
'__homeserver__/_matrix/client/versions'. If there is
|
|
no data, i.e. data (b) is empty, then use '' for it.
|
|
Optionally, --access-token can be used to overwrite
|
|
the access token from credentials (if needed). See
|
|
tests/test-rest.sh for an example.
|
|
--set-avatar AVATAR_MXC_URI
|
|
Set your avatar. Details:: Set the avatar MXC resource
|
|
used by matrix-commander. Provide one MXC URI that
|
|
looks like this 'mxc://example.com/SomeStrangeUriKey'.
|
|
--get-avatar [USER ...]
|
|
Get an avatar. Details:: Get the avatar MXC resource
|
|
used by matrix-commander, or one or multiple other
|
|
users. Specify zero or more user ids. If no user id is
|
|
specified, the avatar of matrix-commander will be
|
|
fetched. If one or more user ids are given, the
|
|
avatars of these users will be fetched. As response
|
|
both MXC URI as well as URL will be printed.
|
|
--get-profile [USER ...]
|
|
Get a user profile. Details:: Get the user profile
|
|
used by matrix-commander, or one or multiple other
|
|
users. Specify zero or more user ids. If no user id is
|
|
specified, the user profile of matrix-commander will
|
|
be fetched. If one or more user ids are given, the
|
|
user profiles of these users will be fetched. As
|
|
response display name and avatar MXC URI as well as
|
|
possible additional profile information (if present)
|
|
will be printed. One line per user will be printed.
|
|
--get-room-info [ROOM ...]
|
|
Get the room information. Details:: Get the room
|
|
information such as room display name, room alias,
|
|
room creator, etc. for one or multiple specified
|
|
rooms. The included room 'display name' is also
|
|
referred to as 'room name' or incorrectly even as room
|
|
title. If one or more room are given, the room
|
|
informations of these rooms will be fetched. If no
|
|
room is specified, the room information for the
|
|
default room configured for matrix-commander is
|
|
fetched. Rooms can be given via room id (e.g.
|
|
'\!SomeRoomId:matrix.example.com'), canonical (full)
|
|
room alias (e.g. '#SomeRoomAlias:matrix.example.com'),
|
|
or short alias (e.g. 'SomeRoomAlias' or
|
|
'#SomeRoomAlias'). As response room id, room display
|
|
name, room canonical alias, room topic, room creator,
|
|
and room encryption are printed. One line per room
|
|
will be printed. Since either room id or room alias
|
|
are accepted as input and both room id and room alias
|
|
are given as output, one can hence use this option to
|
|
map from room id to room alias as well as vice versa
|
|
from room alias to room id. Do not confuse this option
|
|
with the options '--get-display-name' and '--set-
|
|
display-name', which get/set the user display name,
|
|
not the room display name.
|
|
--get-client-info Print client information. Details:: Print information
|
|
kept in the client, i.e. matrix-commander. Output is
|
|
printed in JSON format.
|
|
--has-permission ROOM BAN|INVITE|KICK|NOTIFICATIONS|REDACT|etc [ROOM BAN|INVITE|KICK|NOTIFICATIONS|REDACT|etc ...]
|
|
Inquire about permissions. Details:: Inquire if user
|
|
used by matrix-commander has permission for one or
|
|
multiple actions in one or multiple rooms. Each
|
|
inquiry requires 2 parameters: the room id and the
|
|
permission type. One or multiple of these parameter
|
|
pairs may be specified. For each parameter pair there
|
|
will be one line printed to stdout. Values for the
|
|
permission type are 'ban', 'invite', 'kick',
|
|
'notifications', 'redact', etc. See
|
|
https://spec.matrix.org/v1.2/client-server-
|
|
api/#mroompower_levels.
|
|
--import-keys FILE PASSPHRASE FILE PASSPHRASE
|
|
Import Megolm decryption keys from a file. Details::
|
|
This is an optional argument. If used it must be
|
|
followed by two values. (a) a file name from which the
|
|
keys will be read. (b) a passphrase with which the
|
|
file can be decrypted with. The keys will be added to
|
|
the current instance as well as written to the
|
|
database. See also --export-keys.
|
|
--export-keys FILE PASSPHRASE FILE PASSPHRASE
|
|
Export all the Megolm decryption keys of this device.
|
|
Details:: This is an optional argument. If used it
|
|
must be followed by two values. (a) a file name to
|
|
which the keys will be written to. (b) a passphrase
|
|
with which the file will be encrypted with. Note that
|
|
this does not save other information such as the
|
|
private identity keys of the device.
|
|
--room-set-alias ROOM_ALIAS ROOM [ROOM_ALIAS ROOM ...], --room-put-alias ROOM_ALIAS ROOM [ROOM_ALIAS ROOM ...]
|
|
Add aliases to rooms. Details:: Add an alias to a
|
|
room, or aliases to multiple rooms. Provide pairs of
|
|
arguments. In each pair, the first argument must be
|
|
the alias you want to assign to the room given via
|
|
room id in the second argument of the pair. E.g. the 4
|
|
arguments 'a1 r1 a2 r2' would assign the alias 'a1' to
|
|
room 'r1' and the alias 'a2' to room 'r2'. If you just
|
|
have one single pair then the second argument is
|
|
optional. If just a single value is given (an alias)
|
|
then this alias is assigned to the default room of
|
|
matrix-commander (as found in credentials file). In
|
|
short, you can have just a single argument or an even
|
|
number of arguments forming pairs. You can have
|
|
multiple room aliases per room. So, you may add
|
|
multiple aliases to the same room. A room alias looks
|
|
like this: '#someRoomAlias:matrix.example.org'. Short
|
|
aliases like 'someRoomAlias' or '#someRoomAlias' are
|
|
also accepted. In case of a short alias, it will be
|
|
automatically prefixed with '#' and the homeserver
|
|
will be automatically appended. Adding the same alias
|
|
multiple times to the same room results in an error.
|
|
--room-put-alias is eqivalent to --room-set-alias.
|
|
--room-resolve-alias ROOM_ALIAS [ROOM_ALIAS ...]
|
|
Show room ids corresponding to room aliases. Details::
|
|
Resolves a room alias to the corresponding room id, or
|
|
multiple room aliases to their corresponding room ids.
|
|
Provide one or multiple room aliases. A room alias
|
|
looks like this: '#someRoomAlias:matrix.example.org'.
|
|
Short aliases like 'someRoomAlias' or '#someRoomAlias'
|
|
are also accepted. In case of a short alias, it will
|
|
be automatically prefixed with '#' and the homeserver
|
|
from the default room of matrix-commander (as found in
|
|
credentials file) will be automatically appended.
|
|
Resolving an alias that does not exist results in an
|
|
error. For each room alias one line will be printed to
|
|
stdout with the result.
|
|
--room-delete-alias ROOM_ALIAS [ROOM_ALIAS ...]
|
|
Delete one or multiple rooms aliases. Details::
|
|
Provide one or multiple room aliases. You can have
|
|
multiple room aliases per room. So, you may delete
|
|
multiple aliases from the same room or from different
|
|
rooms. A room alias looks like this:
|
|
'#someRoomAlias:matrix.example.org'. Short aliases
|
|
like 'someRoomAlias' or '#someRoomAlias' are also
|
|
accepted. In case of a short alias, it will be
|
|
automatically prefixed with '#' and the homeserver
|
|
from the default room of matrix-commander (as found in
|
|
credentials file) will be automatically appended.
|
|
Deleting an alias that does not exist results in an
|
|
error.
|
|
--get-openid-token [USER ...]
|
|
Get an OpenID token. Details:: Get an OpenID token for
|
|
matrix-commander, or for one or multiple other users.
|
|
It prints an OpenID token object that the requester
|
|
may supply to another service to verify their identity
|
|
in Matrix. See http://www.openid.net/. Specify zero or
|
|
more user ids. If no user id is specified, an OpenID
|
|
for matrix-commander will be fetched. If one or more
|
|
user ids are given, the OpenID of these users will be
|
|
fetched. As response the user id(s) and OpenID(s) will
|
|
be printed.
|
|
--room-get-visibility [ROOM ...]
|
|
Get the visibility of one or more rooms. Details::
|
|
Provide zero or more room ids as arguments. If no
|
|
argument is given, then the default room of matrix-
|
|
commander (as found in credentials file) will be used.
|
|
For each room the visibility will be printed.
|
|
Currently, this is either the string 'private' or
|
|
'public'. As response one line per room will be
|
|
printed to stdout.
|
|
--room-get-state [ROOM ...]
|
|
Get the state of one or more rooms. Details::Provide
|
|
zero or more room ids as arguments. If no argument is
|
|
given, then the default room of matrix-commander (as
|
|
found in credentials file) will be used. For each room
|
|
the state will be printed. The state is a long list of
|
|
events including events like 'm.room.create',
|
|
'm.room.encryption', 'm.room.guest_access',
|
|
'm.room.history_visibility', 'm.room.join_rules',
|
|
'm.room.member', 'm.room.power_levels', etc. As
|
|
response one line per room will be printed to stdout.
|
|
The line can be very long as the list of events can be
|
|
very large. To get output into a human readable form
|
|
pipe output through sed and jq as shown in an example
|
|
in tests/test-setget.sh.
|
|
--delete-device DEVICE [DEVICE ...]
|
|
Delete one or multiple devices. Details:: By default
|
|
devices belonging to matrix-commander will be deleted.
|
|
If the devices belong to a different user, use the
|
|
--user argument to specify the user, i.e. owner. Only
|
|
exactly one user can be specified with the optional
|
|
--user argument. Device deletion requires the user
|
|
password. It must be specified with the --password
|
|
argument. If the server uses only HTTP (and not
|
|
HTTPS), then the password can be visible to attackers.
|
|
Hence, if the server does not support HTTPS this
|
|
operation is discouraged.
|
|
--room-redact ROOM_ID EVENT_ID REASON [ROOM_ID EVENT_ID REASON ...], --room-delete-content ROOM_ID EVENT_ID REASON [ROOM_ID EVENT_ID REASON ...]
|
|
Strip information out of one or several events.
|
|
Details:: Strip information from events, e.g.
|
|
messages. Redact is used in the meaning of 'strip,
|
|
wipe, black-out', not in the meaning of 'edit'. This
|
|
action removes, deletes the content of an event while
|
|
not removing the event. You can wipe text from a
|
|
previous message, etc. Typical Matrix clients like
|
|
Element will delete messages, images and other objects
|
|
from the GUI once they have been redacted. So, --room-
|
|
redact is a way to delete a message, images, etc. The
|
|
content is wiped, the GUI deletes the message, but the
|
|
server keeps the event history. Note, while this
|
|
deletes from the client (GUI, e.g. Element), it does
|
|
not delete from the database on the server. So, this
|
|
call is not a way to clean up the server database.
|
|
Each redact (wipe, strip, delete) operation requires
|
|
exactly 3 arguments. The argument triples are: (a) the
|
|
room id. (b) the id of the event to be redacted. (c) a
|
|
string containing the reason for the redaction. Use ''
|
|
if you do not want to give a reason. So, the total
|
|
number of arguments used with --room-redact must be a
|
|
multiple of 3, but we also accept 2 in which case only
|
|
one redaction will be done without specifying a
|
|
reason. Event ids start with the dollar sign ($).
|
|
Depending on your shell, you might have to escape the
|
|
'$' to '\$'. --room-delete-content is an alias for
|
|
--room-redact. They can be used interchangeably.
|
|
--whoami Print your user id. Details:: Print the user id used
|
|
by matrix-commander (itself). One can get this
|
|
information also by looking at the credentials file.
|
|
--no-ssl Skip SSL verification. Details:: By default (if this
|
|
option is not used) the SSL certificate is validated
|
|
for the connection. But, if this option is used, then
|
|
the SSL certificate validation will be skipped. This
|
|
is useful for home-servers that have no SSL
|
|
certificate. If used together with the "--ssl-
|
|
certificate" parameter, this option is meaningless and
|
|
an error will be raised.
|
|
--ssl-certificate SSL_CERTIFICATE_FILE
|
|
Use your own SSL certificate. Details:: Use this
|
|
option to use your own local SSL certificate file.
|
|
This is an optional parameter. This is useful for home
|
|
servers that have their own SSL certificate. This
|
|
allows you to use HTTPS/TLS for the connection while
|
|
using your own local SSL certificate. Specify the path
|
|
and file to your SSL certificate. If used together
|
|
with the "--no-ssl" parameter, this option is
|
|
meaningless and an error will be raised.
|
|
--file-name FILE [FILE ...]
|
|
Specify one or multiple file names for some actions.
|
|
Details:: This is an optional argument. Use this
|
|
option in combination with options like --download to
|
|
specify one or multiple file names. Ignored if used by
|
|
itself without an appropriate corresponding action.
|
|
--key-dict KEY_DICTIONARY [KEY_DICTIONARY ...]
|
|
Specify one or multiple key dictionaries for
|
|
decryption. Details:: One or multiple decryption
|
|
dictionaries are provided by the --upload action as a
|
|
result. A decryption dictionary is a string like this:
|
|
"{'v': 'v2', 'key': {'kty': 'oct', 'alg': 'A256CTR',
|
|
'ext': True, 'k': 'somekey', 'key_ops': ['encrypt',
|
|
'decrypt']}, 'iv': 'someiv', 'hashes': {'sha256':
|
|
'someSHA'}}". If you have a list of key dictionaries
|
|
and want to skip one, use the empty string.
|
|
--plain Disable encryption for a specific action. Details:: By
|
|
default, everything is always encrypted. Actions that
|
|
support this option are: --upload, --room-create, and
|
|
--room-dm-create. Rooms are by default created
|
|
encrypted; to overwrite that and to create a room with
|
|
encryption disabled use '--plain'. See the individual
|
|
commands.
|
|
--separator SEPARATOR
|
|
Set a custom separator used for certain print outs.
|
|
Details:: By default, i.e. if --separator is not used,
|
|
4 spaces are used as separator between columns in
|
|
print statements. You could set it to '\t' if you
|
|
prefer a tab, but tabs are usually replaced with
|
|
spaces by the terminal. So, that might not give you
|
|
what you want. Maybe ' || ' is an alternative choice.
|
|
--access-token ACCESS_TOKEN
|
|
Set a custom access token for use by certain actions.
|
|
Details:: It is an optional argument. By default
|
|
--access-token is ignored and not used. It is used by
|
|
the --delete-mxc, --delete-mxc-before, and --rest
|
|
actions.
|
|
--password PASSWORD Specify a password for use by certain actions.
|
|
Details:: It is an optional argument. By default
|
|
--password is ignored and not used. It is used by '--
|
|
login password' and '--delete-device' actions. If not
|
|
provided for --login the user will be queried via
|
|
keyboard.
|
|
--homeserver HOMESERVER_URL
|
|
Specify a homeserver for use by certain actions.
|
|
Details:: It is an optional argument. By default
|
|
--homeserver is ignored and not used. It is used by '
|
|
--login' action. If not provided for --login the user
|
|
will be queried via keyboard.
|
|
--device DEVICE_NAME Specify a device name, for use by certain actions.
|
|
Details:: It is an optional argument. By default
|
|
--device is ignored and not used. It is used by '--
|
|
login', '--verify manual' and '--verify emojireq'
|
|
actions. If not provided for --login the user will be
|
|
queried via keyboard. If you want the default value
|
|
specify ''. Multiple devices (with different device
|
|
id) may have the same device name. In short, the same
|
|
device name can be assigned to multiple different
|
|
devices if desired.
|
|
--sync FULL|OFF Choose synchronization options. Details:: This option
|
|
decides on whether the program synchronizes the state
|
|
with the server before a 'send' action. Currently two
|
|
choices are offered: 'full' and 'off'. Provide one of
|
|
these choices. The default is 'full'. If you want to
|
|
use the default, then there is no need to use this
|
|
option. If you have chosen 'full', the full state, all
|
|
state events will be synchronized between this program
|
|
and the server before a 'send'. If you have chosen
|
|
'off', synchronization will be skipped entirely before
|
|
the 'send' which will improve performance.
|
|
-o TEXT|JSON|JSON-MAX|JSON-SPEC, --output TEXT|JSON|JSON-MAX|JSON-SPEC
|
|
Select an output format. Details:: This option decides
|
|
on how the output is presented. Currently offered
|
|
choices are: 'text', 'json', 'json-max', and 'json-
|
|
spec'. Provide one of these choices. The default is
|
|
'text'. If you want to use the default, then there is
|
|
no need to use this option. If you have chosen 'text',
|
|
the output will be formatted with the intention to be
|
|
consumed by humans, i.e. readable text. If you have
|
|
chosen 'json', the output will be formatted as JSON.
|
|
The content of the JSON object matches the data
|
|
provided by the matrix-nio SDK. In some occasions the
|
|
output is enhanced by having a few extra data items
|
|
added for convenience. In most cases the output will
|
|
be processed by other programs rather than read by
|
|
humans. Option 'json-max' is practically the same as
|
|
'json', but yet another additional field is added. The
|
|
data item 'transport_response' which gives information
|
|
on how the data was obtained and transported is also
|
|
being added. For '--listen' a few more fields are
|
|
added. In most cases the output will be processed by
|
|
other programs rather than read by humans. Option
|
|
'json-spec' only prints information that adheres
|
|
1-to-1 to the Matrix Specification. Currently only the
|
|
events on '--listen' and '--tail' provide data exactly
|
|
as in the Matrix Specification. If no data is
|
|
available that corresponds exactly with the Matrix
|
|
Specification, no data will be printed. In short,
|
|
currently '--json-spec' only provides outputs for '--
|
|
listen' and '--tail'. All other arguments like '--get-
|
|
room-info' will print no output.
|
|
--room-invites [LIST|JOIN|LIST+JOIN]
|
|
List room invitations and/or join invited rooms.
|
|
Details:: This option takes zero or one argument. If
|
|
no argument is given, 'list' is assumed which will
|
|
list all room invitation events as they are received.
|
|
Listing will print the room id and other information
|
|
to standard output. 'join' will join the room(s) each
|
|
time a room invitation is received. 'list+join' will
|
|
do both, list the invitations as well as automatically
|
|
join the rooms to which an invitation was received. '
|
|
--room-invites' can be combined with '--listen'. If
|
|
and only if '--listen forever' is used, will the
|
|
program listen continuously for room invites. In all
|
|
other cases, the program only looks for room
|
|
invitation events once; and it does so before any
|
|
possible listening to messages. Warning: events are
|
|
usually delivered once. So, if you listen for and list
|
|
invites you will get them and list them the first time
|
|
you run '--room-invites list'. On the second run of '
|
|
--room-invites list' the events will not be replayed
|
|
and not be listed. Hence, if you list the invites, you
|
|
might want to store the output (room id) so that you
|
|
can join the room later with '--room-join' for
|
|
example. Don't confuse this option with --room-invite.
|
|
-v [PRINT|CHECK], -V [PRINT|CHECK], --version [PRINT|CHECK]
|
|
Print version information or check for updates.
|
|
Details:: This option takes zero or one argument. If
|
|
no argument is given, 'print' is assumed which will
|
|
print the version of the currently installed
|
|
'PROG_WITHOUT_EXT' package. 'check' is the
|
|
alternative. '{CHECK}' connects to https://pypi.org
|
|
and gets the version number of latest stable release.
|
|
There is no 'calling home' on every run, only a 'check
|
|
pypi.org' upon request. Your privacy is protected. The
|
|
new release is neither downloaded, nor installed. It
|
|
just informs you. After printing version information
|
|
the program will continue to run. This is useful for
|
|
having version number in the log files.
|
|
|
|
You are running version 7.7.0 2024-09-04. Enjoy, star on Github and contribute
|
|
by submitting a Pull Request. Also have a look at matrix-commander-tui.
|