Configuration

iamb is configurable via a JSON configuration file located in the configuration directory. By default, the configuration directory is determined by dirs::config_dir, but you can override it at startup with the -C command-line flag.

Profiles

You can configure a Matrix account in your config.json by adding a new field to the "profiles" object. For example, if you had two different accounts on your homeserver:

{
    "profiles": {
        "admin": {
            "user_id": "@user1:example.com",
            "url": "https://example.com"
        },
        "user": {
            "user_id": "@user2:example.com",
            "url": "https://example.com"
        }
    },
    "default_profile": "user"
}

With the "default_profile" field set, iamb will default to using the user profile at startup. You can manually specify what you want via the -P flag. For example:

$ iamb -P admin
Logging in for @user1:example.com...

Several of the fields that you can place under the global configuration can also be placed within profile configurations to achieve per-profile values:

  • "settings"
  • "dirs"
  • "layout"

Settings

NameDefaultDescription
default_roomA default room name or username to open at startup, in place of showing the welcome screen.
log_level"info"Configures the minimum log level. Valid values are "trace", "debug", "info", "warn" or "error".
open_commandConfigures a command to use for opening downloads instead of the default. (e.g., ["my-open", "--file"] to run a custom script
request_timeout120How long to wait in seconds before timing out requests to the homeserver.
reaction_displaytrueWhether to display message reactions. You can use this or reaction_shortcode_display if your terminal doesn’t show Emojis well.
reaction_shortcode_displayfalseWhether to show the shortcode value instead of the Emoji for reactions. If no shortcode is available, then it won’t be displayed.
read_receipt_sendtrueWhether to send read receipts for viewed rooms.
read_receipt_displaytrueWhether to display read receipts next to messages in the room scrollback.
typing_notice_sendtrueWhether to send notifications to other room members when typing.
typing_notice_displaytrueWhether to display the typing notifications bar.
users{}Configure how other users get displayed in the client. See User Display.
username_display"username"Configure what name is shown for senders. Valid values are "username" (e.g., @user:example.org), "localpart" (e.g., user), or "displayname" (e.g., User Name)

For example, if you wanted to raise the timeout to accommodate a long initial sync, and show more log messages, you could put the following into your config.json:

{
    "settings": {
        "log_level": "debug",
        "request_timeout": 180
    }
}

Startup Layout

You can configure what windows get shown when iamb starts by adding a "layout" object.

Restore Previous Layout

By default, the client will try to restore all of the tabs and windows from the last time it was run. You can explicitly configure this behaviour with:

{
    "layout": { "style": "restore" }
}

New Window

If you want to see a single new window each time you start up, you can set:

{
    "layout": { "style": "new" }
}

This will show the :welcome window by default, but you can set "default_room" to change it to something else.

Configured Layout

If you want to start up with the same layout every time regardless of the state at last exit, you can specify an array of tabs and the window tree in each one:

{
    "layout": {
        "style": "config",
        "tabs": [
            {
                "split": [
                    { "window": "#room1:example.org" },
                    { "window": "#room2:example.org" }
                ]
            },
            {
                "split": [
                    {
                        "split": [
                            { "window": "#room3:example.org" },
                            { "window": "#room4:example.org" }
                        ]
                    },
                    { "window": "@user:example.org" }
                ]
            }
        ]
    }
}

Directories

iamb will use the standard directories for your operating system, but you can override them by placing a "dirs" field in your config.json containing any of the following fields:

NameDefaultDescription
cachedirs::cache_dirDirectory for iamb data and output that can be safely deleted.
logs${cache}/logsOutput directory for iamb logs.
downloadsdirs::download_dirOutput directory for downloaded attachments.

User Display

You can override how individual users get displayed in the scrollback using the "users" field of the "settings" object.

NameDefaultDescription
colorDetermined per-userThe color to use when showing this user on the screen.
nameDetermined per-userThe name to use when showing this user on the screen.

Valid values for the "colors" field are:

  • "black"
  • "blue"
  • "cyan"
  • "dark-gray"
  • "gray"
  • "green"
  • "light-blue"
  • "light-cyan"
  • "light-green"
  • "light-magenta"
  • "light-red"
  • "light-yellow"
  • "magenta"
  • "none"
  • "red"
  • "white"
  • "yellow"

For example, if you wanted to override how a bot in a room gets displayed:

{
    "settings": {
        "users": {
            "@jenkins:example.com": {
                "name": "jenkins (CI BOT)",
                "color": "light-red"
            }
        }
    }
}