Introduction

Welcome to the gomuks docs!

Discussion

Matrix room: #gomuks:maunium.net

Installation

Installing a package

The releases on GitHub contain binaries and debian packages: https://github.com/tulir/gomuks/releases

GitLab CI builds binaries for each commit: https://mau.dev/tulir/gomuks/pipelines (currently available for linux/amd64, linux/arm, linux/arm64, darwin/amd64, darwin/arm64 and windows/amd64).

The release and CI binaries for Linux and Windows are statically built and have no dependencies at all. The binaries for macOS require installing libolm, either with brew install libolm or by placing libolm.3.dylib from the CI in the same directory as the gomuks binary.

There are also community maintained packages for several distributions. If you've made a new distro package, please add it to the list below.

Compiling from source

  1. Install Go 1.13 or higher.
    • If you want end-to-end encryption, also install libolm-dev (3.x required, 2.x won't work) and C/C++ compilers.
    • If you don't want encryption, disable CGO with export CGO_ENABLED=0.
  2. Clone the repo: git clone https://github.com/tulir/gomuks.git && cd gomuks
  3. Build: go build (alternatively, use go install to build to $GOPATH/bin instead of the current directory)

Simply pull changes (git pull) and run go build again to update.

Commands

General

  • /help - View command list.
  • /quit - Close gomuks.
  • /clearcache - Clear room state and close gomuks.
  • /logout - Log out, clear caches and go back to the login view.
  • /fingerprint - Shows the Device ID and fingerprint, allowing verification of the session.
  • /toggle <thing> - Toggle user preferences.
    • rooms - Room list sidebar.
    • users - User list sidebar.
    • baremessages - Bare message mode where the sender name is inline with the messages.
    • images - Text image rendering.
    • typingnotif - Outgoing typing notifications.
    • emojis - :emoji: conversion when sending messages.
    • html - HTML input.
    • markdown - Markdown input.
    • downloads - Automatic downloads (this will also prevent images from working).
    • notifications - Desktop notifications.
    • unverified - Sending (e2ee keys for) messages to unverified devices. You need restart gomuks for this setting to take effect.

Media

Tab-completing file paths is supported in all these commands.

  • /download [path] - Downloads file from selected message. If path is not specified, it defaults to <download_dir>/<message.body>. download_dir defaults to $HOME/Downloads.
  • /open [path] - Download file from selected message and open it with xdg-open. If path is not specified, the file will be downloaded to the media cache.
  • /upload <path> - Upload the file at the given path to the current room. Note that to include audio/video file metadata (dimensions and duration), you must have ffprobe installed.

Sending special messages

  • /me <text> - Send an emote.
  • /notice <text> - Send a notice (generally used for bot messages).
  • /rainbow <text> - Send rainbow text (markdown not supported).
  • /rainbowme <text> - Send rainbow text in an emote.
  • /reply [text] - Reply to the selected message. If text is not specified, the next message will be used.
  • /react <reaction> - React to the selected message.
  • /redact [reason] - Redact the selected message.
  • /edit - Edit the selected message.

Encryption

These commands support tab-completing file paths and user/device IDs using the displaynames of users/devices.

Accepting incoming interactive verification requests is not yet supported, only outgoing requests via /verify work.

  • /fingerprint - View the fingerprint of your device (for legacy/non-interactive verification).
  • /devices <user id> - View the device list of a user.
  • /device <user id> <device id> - Show info about a specific device.
  • /unverify <user id> <device id> - Un-verify a device.
  • /blacklist <user id> <device id> - Blacklist a device. Message keys are never sent to blacklisted devices.
  • /verify <user id> <device id> [fingerprint] - Verify a device. If the fingerprint is not provided, interactive emoji verification will be started.
  • /export <path> - Export all message decryption keys to the given path.
  • /export-room <path> - Export message decryption keys for the current room to the given path.
  • /import <path> - Import message decryption keys from the given path.

Rooms

Creating

  • /pm <user id> [...] - Start a private chat with the given user(s).
  • /create [room name] - Create a new room.

Joining

  • /join <room> [server] - Join the room with the given room ID or alias, optionally through the given server.
  • /accept (in a room you're invited to) - Accept the invite.
  • /reject (in a room you're invited to) - Reject the invite.

Existing

  • /invite <user id> - Invite the given user ID to the room.
  • /roomnick <name> - Change your per-room displayname.
  • /tag <tag> <priority> - Add the room to <tag>. <tag> should start with u. and <priority> should be a float between 0 and 1. Rooms are sorted in ascending priority order.
  • /untag <tag> - Remove the room from <tag>.
  • /tags - List the tags the room is in.

Leaving

  • /leave - Leave the current room.
  • /kick <user id> [reason] - Kick a user.
  • /ban <user id> [reason] - Ban a user.
  • /unban <user id> - Unban a user.

Aliases

  • /alias add <localpart> - Add #<localpart>:your.server as an address for the current room.
  • /alias remove <localpart> - Remove #<localpart>:your.server (can be ran in any room).
  • /alias resolve <alias> - Resolve <alias> or #<alias>:your.server and reply with the room ID.

Raw events

  • /send <room id> <event type> <content> - Send a custom event.
  • /setstate <room id> <event type> <state key/-> <content> - Change room state.
  • /msend <event type> <content> - Send a custom event to the current room.
  • /msetstate <event type> <state key/-> <content> - Change room state in the current room.
  • /id - Get the current room ID.

Debugging

  • /hprof - Create a heap profile and write it to gomuks.heap.prof in the current directory.
  • /cprof <seconds> - Profile the CPU usage for the given number of seconds and write it to gomuks.cpu.prof.
  • /trace <seconds> - Trace calls for the given number of seconds and write traces to gomuks.trace.

Shortcuts

Keyboard

Ctrl and Alt are interchangeable in most keybindings, but the other one may not work depending on your terminal emulator.

  • Switch rooms: Ctrl + , Ctrl +
  • Scroll chat (page): PgUp, PgDown
  • Jump to room: Ctrl + K, type part of a room's name, then Tab and Enter to navigate and select room
  • Plaintext mode: Ctrl + L
  • Newline: Alt + Enter
  • Autocompletion: Tab (emojis, usernames, room aliases and commands)

Editing messages

and can be used at the start and end of the input area to jump to edit the previous or next message respectively.

Selecting messages

After using commands that require selecting messages (e.g. /reply and /redact), you can move the selection with and confirm with Enter.

Mouse

  • Click to select message (for commands such as /reply that act on a message)
  • Ctrl + click on image to open in your default image viewer (xdg-open)
  • Click on a username to insert a mention of that user into the composer

Debugging

If something doesn't work but it doesn't crash, check the /tmp/gomuks/debug.log file for any errors. You can override the location of this file with the DEBUG_DIR environment variable.

Developing

Set DEBUG=1 to enable partial deadlock detection and to write panics to stdout instead of a file.

To build and run with race detection, use go install -race and set GORACE='history_size=7 log_path=/tmp/gomuks/race.log' when starting gomuks, then check /tmp/gomuks/race.log.<pid>. Note that race detection will use a lot of extra resources.

Proper debuggers are too fancy, but normal prints won't work in a TUI application. To write to the debug log mentioned previously, use the maunium.net/go/gomuks/debug package:

package foo

import (
	"maunium.net/go/gomuks/debug"
)

func Foo() {
	debug.Print("WHY ISN'T IT WORKING?!?!?")
	debug.PrintStack()
}