📢 🆕 💥 Latest News! 🔥 📣 🎉

Summary, TLDR

matrix-commander

What for? Why? For whom? Use cases?

Give it a Star

Features

First Run, Set Up, Credentials File, End-to-end Encryption

Verification

Room Operations, Actions on Rooms

Sending

Listening, Receiving

Dependencies and Installation

Documentation and Resources

Examples of calling matrix-commander

$ matrix-commander --login password # first run; will configure everything
$ matrix-commander --login sso # alternative first run with Single Sign-On;
$ # this will configure everything on a headless server w/o a browser
$ # this created a credentials.json file, and a store directory.
$ # optionally, if you want you can move credentials to app config directory
$ mkdir $HOME/.config/matrix-commander # optional
$ mv -i credentials.json $HOME/.config/matrix-commander/
$ # optionally, if you want you can move store to the app share directory
$ mkdir $HOME/.local/share/matrix-commander # optional
$ mv -i store $HOME/.local/share/matrix-commander/
$ # Now you are ready to run program for a second time
$ # Let us verify the device/room to where we want to send messages
$ # The other device will issue a "verify by emoji" request
$ matrix-commander --verify
$ # Now program is both configured and verified, let us send the first message
$ matrix-commander -m "First message!"
$ matrix-commander --debug -m "First message!" # turn debugging on
$ # turn debugging on also for submodules
$ matrix-commander --debug --debug -m "First message!"
$ # turn debugging on, high verbosity
$ matrix-commander --debug --verbose -m "First message!"
$ # turn debugging on, very high verbosity
$ matrix-commander --debug --verbose --verbose -m "First message!"
$ # maximum debugging info
$ matrix-commander --debug --debug --verbose --verbose -m "First message!"
$ matrix-commander --help # print help
$ matrix-commander # this will ask user for message to send
$ matrix-commander --message "Hello World!" # sends provided message
$ echo "Hello World" | matrix-commander # pipe input msg into program
$ matrix-commander -m msg1 -m msg2 # sends 2 messages
$ matrix-commander -m msg1 msg2 msg3 # sends 3 messages
$ df -h | matrix-commander --code # formatting for code/tables
$ matrix-commander -m "<b>BOLD</b> and <i>ITALIC</i>" --html
$ matrix-commander -m "- bullet1" --markdown
$ matrix-commander -m "I :red_heart: you" --emojize
$ matrix-commander -m "Well done :clapping_hands:" --emojize
# See https://unicode.org/emoji/charts/full-emoji-list.html for emoji list
$ # take input from an RSS feed and split large RSS entries into multiple
$ # Matrix messages wherever the pattern "\n\n\n" is found
$ rssfeed | matrix-commander --split "\n\n\n"
$ matrix-commander --credentials usr1room2.json # select credentials file
$ matrix-commander --store /var/storage/ # select store directory
$ # Send to a specific room
$ matrix-commander -m "hi" --room '!YourRoomId:example.com'
$ # some shells require the ! of the room id to be escaped with \
$ matrix-commander -m "hi" --room "\!YourRoomId:example.com"
$ # Send to multiple rooms
$ matrix-commander -m "hi" -r '!r1:example.com' '!r2:example.com'
$ # Send to multiple rooms, another way
$ matrix-commander -m "hi" -r '!r1:example.com' -r '!r2:example.com'
$ # Send to a specific user, DM, direct messaging, using full user id
$ matrix-commander -m "hi" --user '@MyFriend:example.com'
$ # Send to a specific user, DM, direct messaging, using partial user id
$ # It will be assumed that user @MyFriend is on same homeserver
$ matrix-commander -m "hi" --user '@MyFriend'
$ # Send to a specific user, DM, direct messaging, using display name
$ # Careful! Display names might not be unique. Don't DM the wrong person!
$ # To double-check the display names do a --joined-members "*"
$ matrix-commander -m "hi" -u 'Joe'
$ # Send to multiple users
$ matrix-commander -m "hi" -u '@Joe:example.com' '@Jane:example.com'
$ # Send to multiple users, another way
$ matrix-commander -m "hi" -u '@Joe:example.com' -u '@Jane:example.com'
$ # send 2 images and 1 text, text will be sent last
$ matrix-commander -i photo1.jpg photo2.img -m "Do you like my 2 photos?"
$ # send 1 image and no text
$ matrix-commander -i photo1.jpg
$ # pipe 1 image and no text
$ cat image1.jpg | matrix-commander -i -
$ # send 1 audio and 1 text to 2 rooms
$ matrix-commander -a song.mp3 -m "Do you like this song?" \
 -r '!someroom1:example.com' '!someroom2:example.com'
$ # send 2 audios, 1 via stdin pipe
$ audio-generator | matrix-commander -a intro.mp3 -
$ # send a .pdf file and a video with a text
$ matrix-commander -f example.pdf video.mp4 -m "Here are the promised files"
$ # send a .pdf file via stdin pipe
$ pdf-generator | matrix-commander -f -
$ # listen forever, get msgs in real-time and notify me via OS
$ matrix-commander --listen forever --os-notify
$ # listen forever, and show me also my own messages
$ matrix-commander --listen forever --listen-self
$ # listen once, get any new messages and quit
$ matrix-commander --listen once --listen-self
$ matrix-commander --listen once --listen-self | process-in-other-app
$ # listen to tail, get the last N messages and quit
$ matrix-commander --listen tail --tail 10 --listen-self
$ # listen to tail, another way of specifying it
$ matrix-commander --tail 10 --listen-self | process-in-other-app
$ # get the very last message
$ matrix-commander --tail 1 --listen-self
$ # listen to (get) all messages, old and new, and process them in another app
$ matrix-commander --listen all | process-in-other-app
$ # listen to (get) all messages, including own
$ matrix-commander --listen all --listen-self
$ # set, rename device-name, sometimes also called device display-name
$ matrix-commander --set-device-name "my new device name"
$ # set, rename display name for authenticated user
$ matrix-commander --set-display-name "Alex"
$ # get display name for authenticated user, for itself
$ matrix-commander --get-display-name
$ # get display name for other users
$ matrix-commander --get-display-name \
 --user '@user1:example.com' '@user2:example.com'
$ # list all the rooms that I am a member of, all joined rooms
$ matrix-commander --joined-rooms
$ # list all the members of 2 specific rooms
$ matrix-commander --joined-members '!someroomId1:example.com' \
 '!someroomId2:example.com'
$ # list all the members of all rooms that I am member of
$ matrix-commander --joined-members '*'
$ # list all the joined DM rooms of 1 specific user
$ matrix-commander --joined-dm-rooms '@user1:example.com'
$ # list all the joined DM rooms that I am member of
$ matrix-commander --joined-dm-rooms '*'
$ # set presence
$ matrix-commander --set-presence "unavailable"
$ # get presence of matrix-commander itself
$ matrix-commander --get-presence
$ # get presence of other users
$ matrix-commander --get-presence \
 --user '@user1:example.com' '@user2:example.com'
$ # upload file to resource repository
$ matrix-commander --upload "avatar.png"
$ # download file from resource repository via URI (MXC)
$ matrix-commander --download "mxc://example.com/SomeStrangeUriKey"
$ matrix-commander --delete-mxc mxc://... # delete image from database
$ matrix-commander --delete-mxc-before '20.01.2022 19:38:42' 1024000
$ # for more examples of --upload, --download, --delete-mxc,
$ # --delete-mxc-before, --mxc-to-http, see file tests/test-upload.sh
$ matrix-commander --rest GET "" '__homeserver__/_matrix/client/versions'
$ # for more examples of --rest see file tests/test-rest.sh
$ matrix-commander --get-avatar # get its own avatar MXC URI
$ # get avatar MXC URIs of other users
$ matrix-commander --get-avatar '@user1:example.com' '@user2:example.com'
$ matrix-commander --set-avatar mxc://... # set its own avatar MXC URI
$ # for more examples of --set_avatar see tests/test-setget.sh
$ matrix-commander --get-profile # get its own user profile
$ matrix-commander --get-profile '@user1:example.com' '@user2:example.com'
$ matrix-commander --get-room-info # get its default room info
$ matrix-commander --get-room-info '\!room1:example.com' \
 '\!room2:example.com' # get room info for multiple rooms
$ # map from room id to room alias
$ matrix-commander --get-room-info '\!roomId1:example.com'
$ # map from room alias to room id
$ matrix-commander --get-room-info '#roomAlias1:example.com'
$ matrix-commander --get-client-info # get client info
$ matrix-commander --has-permission '!someroomId1:example.com' 'ban'
$ matrix-commander --export-keys mykeys "my passphrase" # export keys
$ matrix-commander --import-keys mykeys "my passphrase" # import keys
$ matrix-commander --get-openid-token # get its own OpenId token
$ # get OpenID tokens for other users
$ matrix-commander --get-openid-token '@user1:example.com' '@user2:example.com'
$ matrix-commander --room-get-visibility # get default room visibility
$ matrix-commander --room-get-visibility \
 '\!someroomId1:example.com' '\!someroomId2:example.com'
$ matrix-commander --room-set-alias '#someRoomAlias:matrix.example.com'
$ matrix-commander --room-set-alias 'someRoomAlias' \
 '\!someroomId1:example.com'
$ matrix-commander --room-resolve-alias '#someRoomAlias:matrix.example.com'
$ matrix-commander --room-resolve-alias '#someRoomAlias1:matrix.example.com' \
 'someRoomAlias2'
$ matrix-commander --room-delete-alias '#someRoomAlias:matrix.example.com'
$ matrix-commander --room-delete-alias '#someRoomAlias1:matrix.example.com' \
 'someRoomAlias2'
$ matrix-commander --room-get-state # get state of default room
$ matrix-commander --room-get-state \
 '\!someroomId1:example.com' '\!someroomId2:example.com'
$ matrix-commander --delete-device "QBUAZIFURK" --password 'mc-password'
$ matrix-commander --delete-device "QBUAZIFURK" "AUIECTSRND" \
 --user '@user1:example.com' --password 'user1-password'
$ # delete a message with event id 'someEventId'
# matrix-commander --room-redact '!someroomId1:example.com' 'someEventId'
$ # delete 2 images from 2 rooms
$ matrix-commander --room-redact \
 '\!someroomId1:example.com' '\$someEventId1' 'Image deleted, obsolete info'
 '\!someroomId2:example.com' '\$someEventId2' 'Image deleted, outdated'
$ # list room invitations
$ matrix-commander --listen once --room-invites list
$ # accepting room invitations, automatically joining rooms to which one is
$ # invited to
$ matrix-commander --listen forever --room-invites list+join
$ # print its own user id
$ matrix-commander --whoami
$ # skip SSL certificate verification for a homeserver without SSL
$ matrix-commander --no-ssl -m "also working without Let's Encrypt SSL"
$ # use your own SSL certificate for a homeserver with SSL and local certs
$ matrix-commander --ssl-certificate mycert.crt -m "using my own cert"
$ # download and decrypt media files like images, audio, PDF, etc.
$ # and store downloaded files in directory "mymedia"
$ matrix-commander --listen forever --listen-self --download-media mymedia
$ # download media files using event-id as file names
$ matrix-commander -l --download-media --download-media-name eventid
$ # create rooms without name and topic, just with alias, use a simple alias
$ matrix-commander --room-create roomAlias1
$ # don't use a well formed alias like '#roomAlias1:example.com' as it will
$ # confuse the server!
$ # BAD: matrix-commander --room-create roomAlias1 '#roomAlias1:example.com'
$ # create rooms with name and topic
$ matrix-commander --room-create roomAlias3 --name 'Fancy Room' \
 --topic 'All about Matrix'
$ matrix-commander --room-create roomAlias4 roomAlias5 \
 --name 'Fancy Room 4' -name 'Cute Room 5' \
 --topic 'All about Matrix 4' 'All about Nio 5'
$ # create DM rooms with user.
$ matrix-commander --room-dm-create '@user1:example.com'
$ # create DM rooms with name, topic, alias
$ matrix-commander --room-dm-create '@user1:example.com' '@user2:example.com' \
 --name 'Fancy DM room 4' -name 'Cute DM room 4' \
 --topic 'All about Matrix 4' 'All about Nio 5' \
 --alias roomAlias1 '#roomAlias2:example.com'
$ # rooms (normal as well as DM) are by default created encrypted,
$ # to overwrite that and to create a room with encryption disabled use --plain
$ matrix-commander --room-create public-room-alias2 --plain
$ matrix-commander --room-dm-create not-encrypted-alias3 --plain
$ # join rooms
$ matrix-commander --room-join '!someroomId1:example.com' \
 '!someroomId2:example.com' '#roomAlias1:example.com'
$ # leave rooms
$ matrix-commander --room-leave '#roomAlias1:example.com' \
 '!someroomId2:example.com'
$ # forget rooms, you have to first leave a room before you forget it
$ matrix-commander --room-forget '#roomAlias1:example.com'
$ # invite users to rooms
$ matrix-commander --room-invite '#roomAlias1:example.com' \
 --user '@user1:example.com' '@user2:example.com'
$ # ban users from rooms
$ matrix-commander --room-ban '!someroom1:example.com' \
 '!someroom2:example.com' \
 --user '@user1:example.com' '@user2:example.com'
$ # unban users from rooms, remember after unbanning you have to invite again
$ matrix-commander --room-unban '!someroom1:example.com' \
 '!someroom2:example.com' \
 --user '@user1:example.com' '@user2:example.com'
$ # kick users from rooms
$ matrix-commander --room-kick '!someroom1:example.com' \
 '#roomAlias2:example.com' \
 --user '@user1:example.com' '@user2:example.com'
$ # set log levels, INFO for matrix-commander and ERROR for modules below
$ matrix-commander -m "test" --log-level INFO ERROR
$ # example of how to quote text correctly, e.g. JSON text
$ matrix-commander -m '{title: "hello", message: "here it is"}'
$ matrix-commander -m "{title: \"hello\", message: \"here it is\"}"
$ matrix-commander -m "{title: \"${TITLE}\", message: \"${MSG}\"}"
$ matrix-commander -m "Don't do this"
$ matrix-commander -m 'He said "No" to me.'
$ matrix-commander --separator " || " # customize column separator in outputs
$ matrix-commander --mxc-to-http mxc://example.com/abc... # get HTTP
$ matrix-commander --devices # to list devices of matrix-commander
$ matrix-commander --discovery-info # print discovery info of homeserver
$ matrix-commander --login-info # list login methods
$ matrix-commander --content-repository-config # list config of content repo
$ matrix-commander --sync off -m Test -i image.svg # a faster send
$ matrix-commander --joined-rooms --output json | jq # get json output in JSON
$ matrix-commander --joined-rooms --output json-max | jq # full details
$ matrix-commander --tail 10 --output json-spec | jq # as specification
$ matrix-commander --joined-rooms --output text # get human-readable output
$ # example of how to use stdin, how to pipe data into the program
$ echo "Some text" | matrix-commander # send a text msg via pipe
$ echo "Some text" | matrix-commander -m - # long form to send text via pipe
$ matrix-commander -m "\-" # send the literal minus sign as a text msg
$ cat image1.png | matrix-commander -i - # send an image via pipe
$ matrix-commander -i - < image1.png # send an image via pipe
$ cat image1.png | matrix-commander -i - -m "text" # send image and text
$ # send 3 images out of which the second will be read from stdin via pipe
$ cat im2.png | matrix-commander -i im1.jpg - im3.jpg # send 3 images
$ echo "text" | matrix-commander -i im1.png # first image, then piped text
$ echo "text" | matrix-commander -i im1.png -m - # same, long version
$ pdf-generator | matrix-commander -f - -m "Here is my PDF file."
$ audio-generator | matrix-commander -a - -m "Like this song?"
$ echo "junk" | matrix-commander -i - -m - # this will fail, not allowed
$ # remember, pipe or stdin, i.e. the "-" can be used at most once
$ cat im.png | matrix-commander -i im1.png - im3.png - im5.png # will fail
$ # sending an event: e.g. reacting with an emoji
$ JSON_REACT_MSC2677='{ "type": "m.reaction",
 "content": { "m.relates_to": { "rel_type": "m.annotation",
 "event_id": "%s", "key": "%s" } } }'
$ TARGET_EVENT="\$...a.valid.event.id" # event to which to react
$ REACT_EMOJI="😀" # how to react
$ printf "$JSON_REACT_MSC2677" "$TARGET_EVENT" "$REACT_EMOJI" |
 matrix-commander --event -
$ # for more examples of "matrix-commander --event" see tests/test-event.sh

Usage

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 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 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 ...]
 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 ...]
 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, --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 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 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 ...]
 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, --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, --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, --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, --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, and room
 encryption are printed. One line per room will be
 printed. If --output is set to JSON a lot more
 information 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-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-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, --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, -V, --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 8.0.5 2025年06月17日. Enjoy, star on Github and contribute
by submitting a Pull Request. Also have a look at matrix-commander-tui.

Autocompletion

Performance and Speed

For Developers

Semantic Versioning

License

Things to do, Things missing

Related Tools and Projects

Final Remarks