matrix-commander 8.0.5
A simple command-line Matrix client
Requires Python: >=3.11
Keywords: Matrix, chat, messaging

# PRE-INSTALLATION

Before you install `matrix-commander` with `pip install matrix-commander`
you *must* have followed these prerequisites steps! Otherwise `pip` will fail.

- Note that even if you install via `pip` you must have a) Python 3.8+
  and b) `libolm` installed.
- Run `python -V` to get your Python version number and assure that it is
  3.8+.
- For e2ee support, python-olm is needed which requires the libolm C
  library (version 3.x). See also https://gitlab.matrix.org/matrix-org/olm.
  Make sure that version 3 is installed. Version 2 will not work.
  To install `libolm` do this:
  - On Debian, Ubuntu and Debian/Ubuntu derivative distributions: `sudo apt install libolm-dev`
  - On Fedora or Fedora derivative distributions do: `sudo dnf install libolm-devel`
  - On MacOS use brew: `brew install libolm`

- For macOS Monterey 12.4 (21F79) (Apple M1 Pro) and similar please follow
  these steps for installation:

  - Install `libolm`, `dbus` and `libmagic` using Homebrew:
      - `brew install libolm dbus libmagic`
  - Install `matrix-commander` using this command:
      - `pip3 install --global-option=build_ext --global-option="-I/opt/homebrew/include/" --global-option="-L/opt/homebrew/lib/" matrix-commander`
  - For more details see Issue #79. Thanks to @KizzyCode for the contribution.

- For macOS x86_64 and similar please follow these steps for installation:

  - `brew install libolm dbus libmagic`
  - `pip3 install poetry`
  - `pip3 install --global-option=build_ext --global-option="-I/usr/local/include/" --global-option="-L/usr/local/lib/" matrix-commander`
  - Notice that the Link and Include directories between ARM (M1, etc.)
    and x86-64 are different.
    So, check for example where file `olm.h` is located on your hard disk.
    That gives you a hint which Include directory to use.
  - For more details see Issue #103. Thanks to @johannes87 for the contribution.

- Installing dependencies of `matrix-commander-tui`
  - `matrix-commander-tui` requires that you install `vipe` from the packge `moreutils`.
    - Read https://www.putorius.net/moreutils.html for installation instructions.
    - As an alternative you could also install `vipe.sh` from https://github.com/0mp/vipe.sh/blob/master/vipe.sh.
  - `matrix-commander-tui` requires that you install `fzf`.
    - Read https://github.com/junegunn/fzf#installation for installation instructions.

[![PyPI - Python Version](
https://img.shields.io/pypi/pyversions/matrix-commander?color=red)](
https://www.python.org/)
[![Built with matrix-nio](
https://img.shields.io/badge/built%20with-matrix--nio-darkgreen)](
https://github.com/poljar/matrix-nio)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](
https://github.com/psf/black)
[![Docker Pulls](https://img.shields.io/docker/pulls/matrixcommander/matrix-commander)](
https://hub.docker.com/r/matrixcommander/matrix-commander/)
[![PyPI - Version](https://img.shields.io/pypi/v/matrix-commander?color=darkblue)](
https://pypi.org/project/matrix-commander)
[![PyPI - Downloads](
https://img.shields.io/pypi/dm/matrix-commander?color=darkblue&label=PyPi%20Downloads
)](https://pypi.org/project/matrix-commander)
[![Nix: package](https://img.shields.io/badge/Nix-package-6fa8dc.svg)](
https://search.nixos.org/packages?query=matrix-commander)

<p>
<img
src="https://raw.githubusercontent.com/8go/matrix-commander/master/logos/mc.svg"
alt="MC> logo" height="150">

<p>
<a href="https://matrix.org/ecosystem/clients/matrix-commander/">
<img src="https://github.com/matrix-org/matrix.org/blob/main/static/images/matrix-logo.svg"
alt="made for Matrix" height="100"></a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="https://pypi.org/project/matrix-commander/">
<img src="https://pypi.org/static/images/logo-large.516e776d.svg"
alt="get it on PyPi" height="100"></a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="https://hub.docker.com/r/matrixcommander/matrix-commander">
<img src="https://www.unixtutorial.org/images/software/docker-hub.png"
alt="get it on Docker Hub" height="100"></a>
</p>

# :loudspeaker: :new: :boom: Latest News! :fire: :mega: :tada:

- announcing *digital attestation of releases on PyPi.org*. Please read:
  [PyPi blog article on digital attestation](https://blog.pypi.org/posts/2024-11-14-pypi-now-supports-digital-attestations/).
  `matrix-commander` releases are now digitally attested on
  [PyPi](https://pypi.org/project/matrix-commander/).
  As an example look at https://pypi.org/project/matrix-commander/#matrix_commander-8.0.3.tar.gz .
  You will find `Verified details` in the left column and
  `Uploaded using Trusted Publishing? Yes` as well as
  `The following attestation bundles were made for matrix_commander`
  in the right column. In short, you can trust that the PyPi release
  actually matches the Github source code.
- `matrix-commander` now available on
  [Docker Hub](https://hub.docker.com/r/matrixcommander/matrix-commander)
  and hence easy to install as docker image (:clap: to @pataquets for his PR).
  Install via `docker pull matrixcommander/matrix-commander`.
- `matrix-commander` now available on
  [PyPi](https://pypi.org/project/matrix-commander/)
  and hence easy to install via `pip install matrix-commander`
- available as reproducible
  [Nix package](https://search.nixos.org/packages?query=matrix-commander)
  for NixOS, Debian, Fedora, etc.
- `matrix-commander` is now callable from a Python program as well.
  See [tests/test-send.py](
  https://github.com/8go/matrix-commander/blob/master/tests/test-send.py)
  for an example on how to do that.
- announcing `matrix-commander-rs` :crab:, `matrix-commander` but in Rust.
  See [matrix-commander-rs](https://github.com/8go/matrix-commander-rs).
  Please :star: it if you like the idea. Please contribute if you can,
  please :pray: Thank you!
  :heart:
  

# Summary, TLDR

This simple Matrix client written in Python allows you to send and
receive messages and files, verify other devices, and interact with
your Matrix account or other Matrix users in many ways.
You use it from the terminal (CLI) or integrate it into other simple
Python programs. Enjoy and please :star: star on Github.

# matrix-commander

Simple but convenient CLI-based Matrix client app for sending, receiving,
creating rooms, inviting, verifying, and so much more.

- `matrix-commander` is a simple command-line [Matrix](https://matrix.org/)
  client.
- It is a simple but convenient app to
    - send Matrix text messages as well as text, image, audio, video or
      other arbitrary files
    - listen to and receive Matrix messages, images, audio, video, etc.
    - download media files like images or audio
    - perform Matrix emoji verification
    - performs actions of rooms (create rooms, invite to rooms, etc.)
    - list rooms and room members
    - and much more
- It exclusively offers a command-line interface (CLI).
- Hence the word-play: matrix-command(lin)er
- There is no GUI and there are no windows (except for pop-up windows in
  OS notification)
- It uses the [matrix-nio](https://github.com/poljar/matrix-nio/) SDK
- Both `matrix-nio` and `matrix-commander` are written in Python 3
- Convenient to install via `pip`.

# What for? Why? For whom? Use cases?

Use cases for this program could be
- a bot or part of a bot,
- to automate sending via programs and scripts
- `matrix-nio show case`: as educational material that showcases the use
  of the `matrix-nio` SDK
- `alerter`: to send all sorts of alerts,
- `Gitlab CI automation tool`: some user uses it as Gitlab CI automation tool
   to report build success/failure to their internal Matrix room.
   See [Issue #81](https://github.com/8go/matrix-commander/issues/81).
- `admin tool` or `automation tool`: you needs to create 175 room for the
   roll-out within a company? You want to query some 9000 rooms for
   visibility data? You want to collect profile data of 7000 enterprise or
   public users? `matrix-commander` has many admin capabilities and can
   automate many tasks completely. Many admin jobs can be reduced to running
   a simple bash script or a simple Python program using `matrix-commander`.
- `reminder`: send yourself or others daily/weekly reminders via a cron job.
- `surf report`: an addict surfer uses `matrix-commander` combined with a
   `cron` job to publish daily early morning surf reports for his 3 favorite
   surfing spots to his Element app.
- `juke box`: a user told me he has a large collection of mp3 files on his
  server. He uses `matrix-commander` to send himself a random song from
  his music collection to brighten his day.
- `ticker`: many people send themselves stock prices from one of the many
  public ticker APIs. This is usually a single `curl` command piped into
  `matrix-commander`.
- `poor-man's Matrix client`: if you love the terminal and are too lazy to
   start up an Element desktop app or an Element webpage,
   `matrix-commander` is a a trivial way to fire off some instant
   messages to your friends from the terminal.
- `poor-man's importer or exporter`: you want to get things in and out of
   Matrix?
   Send those 39 holiday picture you have laying around in a holiday folder?
   Or, your best friend just sent you 57 wedding pictures on Element and
   you want to store them? `matrix-commander` can help with importing and
   exporting data.
- `poor man's blogger`: a "blogger" who frequently sends messages and
  images to the same public room(s) could use `matrix-commander` to keep
  his audience informed.
- `poor man's diary`: a person could write a diary or run a gratitude
  journal by sending messages to her/his own diary room or gratitude room.
- `ghost`: `matrix-commander` can be used in an ephemeral fashion, in a
  fire-and-forget style. A single batch command can log in, create a
  new device, send a message, and then log out and delete the device.

# Give it a Star

If you like it, use it, fork it, make a Pull Request or contribute.
Please give it a :star: on Github right now so others find it more easily.
:heart:


# Features

- CLI, Command Line Interface
- Python 3
- Simplicity
- Small footprint, small application (only around 250K)
- Uses `nio-template`
- End-to-end encryption
- Storage for End-to-end encryption
- Storage of credentials
- Supports access token instead of password
- Supports SSO (Single Sign-On)
- Sending messages
- Sending notices
- Sending formatted messages
- Sending MarkDown messages
- Message splitting before sending
- Sending Code-formatted messages
- Sending emojis in messages via shorthand
- Sending to one room
- Sending to multiple rooms
- Sending image files (photos, etc.)
- Sending of media files (music, videos, etc.)
- Sending of arbitrary files (PDF, xls, doc, txt, etc.)
- Sending events such as emoji reactions, or replies as threads
- Using events to edit sent messages
- Supports creating private DM rooms (thanks to PR from @murlock1000)
- Supports DM (direct messaging), sending DMs, listening for DMs
- Listing of joined rooms
- Listing of members of given room(s)
- Receiving messages forever
- Receiving messages once
- Receiving last messages
- Receiving or skipping its own messages
- Receiving and downloading media files
  - including automatic decryption
- Creating new rooms
- Joining rooms
- Leaving rooms
- Forgetting rooms
- Inviting other users to rooms
- Banning from rooms
- Unbanning from rooms
- Kicking from rooms
- Accepting room invites
- Supports renaming of device
- Supports getting and setting display name
- Supports getting and setting presence
- Uploading, downloading, and deleting to/from resource depository
- Listing your devices
- Listing discovery info
- Listing available login methods supported by server
- Supports skipping SSL verification to use HTTP instead of HTTPS
- Supports providing local SSL certificate files
- Supports notification via OS of received messages
- Supports periodic execution via crontab
- Supports room aliases
- Supports multiple output formats like `text` (for human consumption)
  and `json` (for machine consumption and further processing)
- Provides PID files
- Logging (at various levels)
- In-source documentation
- Can be run as a service
- Smart tab completion for shells like bash (thanks to PR from @mizlan :clap:)
- TUI tool for building commands (`matrix-commander-tui`)
- More than 90 options
- More than 300 stars :stars: on Github
- Easy installation, available through `pip`, i.e. available in
  [PyPi](https://pypi.org/project/matrix-commander/) store
- Easy installation, available as docker image on
  [Docker Hub](https://hub.docker.com/r/matrixcommander/matrix-commander)
  (thanks to PR from @pataquets :clap:)
- Easy installation, available in Nix repository as reproducible
  [Nix package](https://search.nixos.org/packages?query=matrix-commander)
- Callable from the terminal, from shells like `bash`, etc.
- Callable from Python programs via the entry point (function) `main`.
- Open source
- Free, GPL3+ license

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

On the first run `matrix-commander` must be executed with the
`--login` argument and the corresponding secondary arguments.
This creates a credentials.json file.
The credentials.json file stores: homeserver, user id,
access token, device id, and default room id. On the first run,
the --login run, it asks some questions if not everything is
provided by arguments, creates the token and device id
and stores everything in the credentials.json file. If desired,
all arguments can be provided via arguments to that log in can
be performed fully in batch.

Since the credentials file holds an access token it
should be protected and secured. One can use different
credential files for different users (or different default rooms).

On creation the credentials file will by default be created in the local
directory, so the users sees it right away. This is fine if you have
only one or a few credential files, but for better maintainability
it is suggested to place your credentials files into directory
`$HOME/.config/matrix-commander/`. When the program looks for
a credentials file it will first look in local directory and then
as secondary choice it will look in directory
`$HOME/.config/matrix-commander/`.

If you want to re-use an existing device id and an existing
access token, you can do so as well, just manually edit the
credentials file. However, for end-to-end encryption this will
NOT work.

End-to-end encryption (e2ee) is enabled by default. It cannot be turned off.
Wherever possible end-to-end encryption will be used. For e2ee to work
efficiently a `store` directory is needed to store e2ee data persistently.
The default location for the store directory is a local directory named
`store`. Alternatively, as a secondary choice the program looks for a store
directory in `$HOME/.local/share/matrix-commander/store/`. The user can always
specify a different location via the --store argument. The `store`
directory will usually be created on the first run.

For specific use cases end-to-end encryption can be disabled. Please see
description of flag `--plain` for details.

From the second time the program is run, and on all
future runs it will use the homeserver, user id
and access token found in the credentials file to log
into the Matrix account. Now this program can be used
to easily send simple text messages, images, and so forth
to the just configured room.

# Verification

As second step after the `--login`, it is recommended to perform an
emoji verification by running `--verify`. Verification is always
interactive, because the emojis need to be confirmed via the keyboard.
If desired `--login` and `--verify` can be done in the same first run.
The program can accept verification request and verify other devices
via emojis. See `--verify` in help for more details.

# Room Operations, Actions on Rooms

The program can create rooms, join, leave and forget rooms.
It can also send invitations to join rooms to
others (given that user has the appropriate permissions) as
well as ban, unban and kick other users from rooms.

# Sending

Messages to send can be provided
1) in the command line (-m or --message)
2) as input from the keyboard (if there is no other input or command)
3) through a pipe from stdin (|), i.e. piped in from another program.

For sending messages the program supports various text formats:
1) text: default
2) html:  HTML formatted text
3) markdown: MarkDown formatted text
4) code: used a block of fixed-sized font, ideal for ASCII art or
   tables, bash outputs, etc.
5) notification
6) split: splits messages into multiple units at given pattern

Photos and images that can be sent. That includes files like
`.jpg`, `.gif`, `.png` or `.svg`.

Arbitrary files like `.txt`, `.pdf`, `.doc`, audio files like `.mp3`
or video files like `.mp4` can also be sent.

Matrix events like sending an emoji reaction, replying as a thread,
message edits can be sent.

# Listening, Receiving

One can listen to one or multiple rooms. Received messages will be displayed
on the screen. If desired, optionally, you can be notified of incoming
messages through the operating system standard notification system, usually a
small pop-up window.

Messages can be received or listened to various ways:
1) Forever: the program runs forever, listens forever, and prints all
   messages as they arrive in real-time.
2) Once: the program prints all the messages that are waiting in the queue,
   i.e. all messages that have been sent in, and after printing them the
   program terminates.
3) Tail: prints the last N read or unread messages of one or multiple
   specified rooms and after printing them the program terminates.

When listening to messages you can also choose to download and decrypt
media. Say, someone is sending a song. The mp3 file can be downloaded
and automatically decrypted for you.

# Dependencies and Installation

- If you install via `pip`, then `pip` will take care of most of the
  dependencies.
  - See https://pypi.org/project/matrix-commander
  - Usually `pip install matrix-commander` will do the trick.
  - But, note that even if you install via `pip` you must have a) Python 3.8+
    and b) `libolm` installed. See `PyPi-Instructions.md`.
  - Run `python -V` to get your Python version number and assure that it is
    3.8+.
  - For e2ee support, python-olm is needed which requires the libolm C
    library (version 3.x). See also https://gitlab.matrix.org/matrix-org/olm.
    Make sure that version 3 is installed. Version 2 will not work.
    To install `libolm` do this:
    - On Debian, Ubuntu and Debian/Ubuntu derivative distributions:
      `sudo apt install libolm-dev`
    - On Fedora or Fedora derivative distributions do:
      `sudo dnf install libolm-devel`
    - On MacOS use brew:
      `brew install libolm`

- For macOS Monterey 12.4 (21F79) (Apple M1 Pro) and similar please follow
  these steps for installation:

  - Install `libolm`, `dbus` and `libmagic` using Homebrew:
      - `brew install libolm dbus libmagic`
  - Install `matrix-commander` using this command:
      - `pip3 install --global-option=build_ext --global-option="-I/opt/homebrew/include/" --global-option="-L/opt/homebrew/lib/" matrix-commander`
  - For more details see Issue #79. Thanks to @KizzyCode for the contribution.

- For macOS x86_64 and similar please follow these steps for installation:

  - `brew install libolm dbus libmagic`
  - `pip3 install poetry`
  - `pip3 install --global-option=build_ext --global-option="-I/usr/local/include/" --global-option="-L/usr/local/lib/"  matrix-commander`
  - Notice that the Link and Include directories between ARM (M1, etc.)
    and x86-64 are different.
    So, check for example where file `olm.h` is located on your hard disk.
    That gives you a hint which Include directory to use.
  - For more details see Issue #103. Thanks to @johannes87 for the contribution.

- If you install a docker image: `matrix-commander` is available on
  [Docker Hub](https://hub.docker.com/r/matrixcommander/matrix-commander)
  and hence easy to install as docker image (:clap: to @pataquets for his PR).
  Install via `docker pull matrixcommander/matrix-commander`.

- If you install it via `git` or via file download then these are the
  dependencies that you must take care of:

    - Python 3.8 or higher installed (3.7 will NOT work)
    - libolm-dev must be installed as it is required by matrix-nio
      - libolm-dev on Debian/Ubuntu, libolm-devel on Fedora, libolm on MacOS
    - matrix-nio must be installed, see https://github.com/poljar/matrix-nio
      - pip3 install --user --upgrade matrix-nio[e2e]
    - python3 package markdown must be installed to support MarkDown format
      - pip3 install --user --upgrade markdown
    - python3 package emoji must be installed to support emojis in text messages
      - pip3 install --user --upgrade emoji
    - python3 package python_magic must be installed to support image sending
      - pip3 install --user --upgrade python_magic
    - if (and only if) you want OS notification support, then the python3
      package notify2 and dbus-python should be installed
      - pip3 install --user --upgrade dbus-python # optional
      - pip3 install --user --upgrade notify2 # optional
    - python3 package urllib must be installed to support media download
      - pip3 install --user --upgrade urllib
    - python3 package pyxdg must be installed to support `XDG_*` env vars.
      Be careful. Multiple packages install in the same directory `xdg` and
      overwrite each other. These packages can be conflicting. Specifically,
      packages `pyxdg` and `xdg` collide. If you already have `xdg` installed
      you cannot just simply install `pyxdg`; in this case you should opt
      for a separate Python environment.
      - pip3 install --user --upgrade pyxdg
    - `matrix_commander/matrix_commander.py` file must be installed, and should
      have execution permissions
      - chmod 755 matrix_commander.py
    - `matrix_commander/matrix-commander` file is recommended for the install,
      and should have execution permissions
      - chmod 755 matrix-commander
    - for a full list or requirements look at the `requirements.txt` file
      - run `pip install -r requirements.txt` to automatically install
        all required Python packages
      - if you e.g. run on a headless server and don't want dbus-python and
        notify2, please remove the corresponding 2 lines from
        the `requirements.txt` file

- Installing dependencies of `matrix-commander-tui`
  - `matrix-commander-tui` requires that you install `vipe` from the package `moreutils`.
    - Read https://www.putorius.net/moreutils.html for installation instructions.
    - As an alternative you could also install `vipe.sh` from https://github.com/0mp/vipe.sh/blob/master/vipe.sh.
  - `matrix-commander-tui` requires that you install `fzf`.
    - Read https://github.com/junegunn/fzf#installation for installation instructions.

# Documentation and Resources

- There are 4 level of details for the documentation. In sorted order from
  short summary to long details:
  - Just the options, no explanation:
    `matrix-commander --usage` or
    [online](https://github.com/8go/matrix-commander/blob/master/help.usage.txt)
    on Github
  - One-liner explanations for each option:
    `matrix-commander --help` or
      [online](https://github.com/8go/matrix-commander/blob/master/help.help.txt)
      on Github
  - Detailed verbose explanations for each option, like a man-page:
    `matrix-commander --manual` or
    [online](https://github.com/8go/matrix-commander/blob/master/help.manual.txt)
    on Github
  - Full documentation, installation, examples, use-cases, etc.:
    `matrix-commander --readme` or
    [online](https://github.com/8go/matrix-commander/blob/master/README.md)
    on Github

# Examples of calling `matrix-commander`

- Alternative 1: Usually `matrix-commander` is called from a terminal
  inside a shell like `bash`, `sh`, `zsh`, your Windows CMD terminal
  or similar. You will find plenty of examples how to use it within
  a terminal just a few lines down.
  Or invoke it via the TUI (Terminal User Interface) tool `matrix-commander-tui`.
- Alternative 2: Sometimes, however, it might be more convenient to call
  `matrix-commander` from within a Python program. This is also possible.
  Import the Python module `matrix_commander` and use the provided
  entry point `main`. An example of how this can be done can be found
  in [tests/test-send.py](
  https://github.com/8go/matrix-commander/blob/master/tests/test-send.py).

```bash
$ 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 eve