Getting started

Requirements

• A terminal with UTF-8 and colors: GNOME Terminal, Konsole, kitty, xterm, tmux, Windows Terminal, macOS Terminal
• An account on a Matrix homeserver, for example @alice:matrix.org

Install

See Installing: with apt on Debian and Ubuntu, from the release archives on Windows and other Linux systems, or from source.

Run

Start the client; on Windows, run Uniform.Chat.exe:

./Uniform.Matrix

Double-clicking Uniform.Chat in a file manager works too: on Linux it opens itself in a terminal window, the desktop's default terminal or the one in the TERMINAL environment variable.

The first time, it asks for your full Matrix user ID, such as @alice:matrix.org. Give the server address too only when the server cannot be found from the user ID, for example http://localhost:8008 for a server of your own on this computer. Then it asks for your password and logs in. After a successful login it saves the user ID and address to your settings, and remembers the session, so later runs start straight away without asking.

You can also give them on the command line, which skips the question: --Matrix:UserId=@alice:matrix.org, and --Matrix:Homeserver=http://localhost:8008 when needed. Without a terminal to ask in, for example with input redirected, the client prints this help instead. Messages are kept in a local database under ~/.local/share/uniform-chat-terminal/, and messages you write are kept there until the server has received them, so nothing is lost when the connection drops.

The window has a menu bar, a room list, the messages of the selected room and its members. Type a message and press Enter to send it; see Interface for menus, keys and /commands.

Settings can be changed in File → Settings, which saves them to ~/.config/uniform-chat-terminal/settings.json; see Settings, which also lists every command-line parameter. They can also go in appsettings.json next to the program, for example "Matrix": { "UserId": "@alice:matrix.org" }. Command-line options override both.

Each run writes its own log under ~/.local/share/uniform-chat-terminal/logs/; View → Logs shows them.

To log out on the server, choose File → Log out. Quitting with Ctrl+Q keeps the session.

Create an account

On the first start, give the user ID you want, such as @alice:example.org, where the part after : is the server, and choose Create account. The client asks for a password twice, then for what the server needs: a registration token from the server's admin, and acceptance of its policies, shown with their addresses. It then creates the account and logs in. Many servers do not let apps create accounts: then make the account on the server's website and log in here.

Delete the account

File → Delete account… asks you to confirm, then for your password. You leave every room, your name and picture are removed, and every device is signed out. The account cannot be used again, and nobody can take its user ID. The client then quits and forgets the user ID.

Troubleshooting

Message	Meaning
M_FORBIDDEN: Invalid username or password	Wrong user ID or password.
No valid m.homeserver.base_url for ...	The server's discovery file is broken; contact its administrator.
M_LIMIT_EXCEEDED ... (retry after N s)	The server limits logins; wait N seconds.