Configuration

iamb is configurable via a TOML 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. An example config can be found in the root of the repo here.

Profiles

You can configure a Matrix account in your config.toml by creating a profiles subsection with a user_id field specifying your account:

[profiles.user]
user_id = "@user2:example.com"

When you start iamb for the first time, it will ask you whether you want to log in with a password (enter p to select), or SSO (enter s to select). If you choose SSO, then a page will open in your browser to go through the SSO authentication flow.

Multiple Profiles

You can create multiple profiles for different accounts or settings by adding additional subsections to the profiles section:

default_profile = "user"

[profiles.admin]
user_id = "@user1:example.com"

[profiles.user]
user_id = "@user2:example.com"

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...

Per-Profile Configuration

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

• dirs
• layout
• macros
• settings

Per-profile values will be merged on top of the global values. For example:

[profiles.user.layout]
style = "restore"

[profiles.admin.layout]
style = "new"

Explicit Homeserver URLs

If your homeserver is located on a different domain than the server part of the user_id and you don’t have a /.well-known entry, then you can explicitly specify the homeserver URL to use:

default_profile = "user"

[profiles.admin]
user_id = "@user1:example.com"
url = "https://example.com"

[profiles.user]
user_id = "@user2:example.com"
url = "https://example.com"

Settings

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.toml:

[settings]
log_level = "debug"
request_timeout = 180

Image Previews

When the settings.image_preview subsection is present, iamb will try to detect an appropriate way to show previews of image attachments:

[settings]
image_preview = {}

There are several different supported ways of showing images:

• "sixel", a method supported by several different terminals (see arewesixelyet.com)
• "iterm2", a method supported by the iTerm2 terminal for macOS
• "kitty", a method supported by the Kitty terminal (requires at least version 0.28.0)
• "halfblocks", a pixelated representation of the image using colored blocks, and used as a fallback

If a method that works for your terminal can’t be autodetected (e.g., when running on Windows or in a terminal that doesn’t provide pixel information), you can manually specify how image previews are done using the "protocol" field:

[settings.image_preview]
protocol.type = "halfblocks"
protocol.font_size = [ 11, 26 ]

The "type" field is one of the three methods from above, and "font_size" can be used to specify the width and height of each character cell in pixels. (Like specifying the "type", this is only necessary if the size in pixels can’t be detected normally using the standard terminal ioctl calls.)

You can control the maximum amount of columns/rows that the images take up in the scrollback using the "size" field:

[settings.image_preview]
size = { height = 10, width = 66 }

Notifications

The settings.notifications section allows enabling notifications for messages sent to rooms not currently open. For example, to enable desktop notifications, you can put the following in your configuration:

[settings.notifications]
enabled = true

See Configuring Room Notifications for how to adjust the per-room notification level.

Notification fields

Sorting Lists

The settings.sort section allows you to customize how lists of rooms or users are sorted in the different iamb windows by specifying which values you want to sort on. Values are provided as an array of fields, with an optional leading ~ to flip the sort order from ascending to descending.

For example, if you wanted to group users in the :members list together by their ascending server name and descending localparts, you could do:

[settings.sort]
members = ["server", "~localpart"]

Sort Fields

Room Fields

User Fields

Startup Layout

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

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"

[[layout.tabs]]
split = [
    { window = "#room1:example.org" },
    { window = "#room2:example.org" }
]

[[layout.tabs]]
split = [
    { split = [ { window = "#room3:example.org" }, { window = "#room4:example.org" } ] },
    { window = "@user:example.org" }
]

Custom Keybindings

You can add custom keybindings in macros subsections, which describes the Vim modes to map the commands to, the input keys you want to map, and the keys that you want it to then run. These keybindings behave like macros when a count is given, and will repeat the target key sequence n times.

For example, you could use the following to map jj to <Esc> in Insert mode and V to <C-W>m in Normal and Visual mode:

[macros.insert]
"jj" = "<Esc>"

[macros."normal|visual"]
"V" = "<C-W>m"

You can also use this to trigger commands. For example, to list all chats when you press ‘gc’ in normal mode use:

[macros.normal]
"gc" = ":chats<Enter>"

The available modes are:

• normal/n for Normal mode
• insert/i for Insert mode
• visual/v for Visual mode
• command/c for Command mode
• select for Select mode
• operator-pending for Operator Pending mode

Use | to specify that something should be mapped in several modes.

If you are unsure how to represent a key, you can you record a macro that use it and then look at its representation in the register. For example, you could do the following to find the value of the left arrow key:

• Type qa to start recording to the a register
• Press the left arrow key
• Press q to stop recording
• Type "ap to paste the contents of the a register, yielding <Left>

Directories

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

User Display

You can override how individual users get displayed in the scrollback using the settings.users section.

Valid values for the color 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" }