IAMB(5)

📦
version 0.0.11 · 3 versions
, in alpine 3.24, nixos 26.05

💖 IAMB(5) — File Formats Manual 💖

okay bestie, gather round 🫶 this is the manual page for config.toml, the config file for iamb. It's giving “tiny file, huge personality” and we're gonna go through every single bit together. No cap, by the end you'll know this file like the back of your hand. 💅

🌸 NAME 🌸

config.toml — configuration file for iamb

🦋 DESCRIPTION 🦋

Configuration must be placed under ~/.config/iamb/ and named config.toml. (If $XDG_CONFIG_HOME is set, then iamb will look for a directory named iamb there instead.)

Example configuration usually comes bundled with your installation and can typically be found in /usr/share/iamb.

As implied by the filename, the configuration is formatted in TOML. Its structure and fields are described below.

✨ CONFIGURATION ✨

These options are sections at the top-level of the file.

  • profiles — A map of profile names containing per-account information. See “PROFILES”.
  • default_profile — The name of the default profile to connect to, unless overwritten by a commandline switch. It should be one of the names defined in the profiles section.
  • settings — Overwrite general settings for iamb. See “SETTINGS” for a description of possible values.
  • layout — Configure the default window layout to use when starting iamb. See “STARTUP LAYOUT” for more information on how to configure this object.
  • macros — Map keybindings to other keybindings. See “CUSTOM KEYBINDINGS” for how to configure this object.
  • dirs — Configure the directories to use for data, logs, and more. See “DIRECTORIES” for the possible values you can set in this object.

🎀 PROFILES 🎀

These options are configured as fields in the profiles object.

  • user_id — The user ID to use when connecting to the server. For example "user" in "@user:matrix.org".
  • url — The URL of the user's server. (For example "https://matrix.org" for "@user:matrix.org".) This is only needed when the server does not have a /.well-known/matrix/client entry.

In addition to the above fields, you can also reuse the following fields to set per-profile overrides of their global values:

  • dirs
  • layout
  • macros
  • settings

✨ Example 1: A single profile ✨

[profiles.personal]
user_id = "@user:matrix.org"

💖 Example 2: Two profiles with a default 💖

In the following example, there are two profiles, “personal” (set to be the default) and “work”. The “work” profile has an explicit URL set for its homeserver.

default_profile = "personal"

[profiles.personal]
user_id = "@user:matrix.org"

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

👑 SETTINGS 👑

These options are configured as an object under the settings key and can be overridden as described in “PROFILES”. Lowkey this is where most of the personalization lives.

  • external_edit_file_suffix — Suffix to append to temporary file names when using the :editor command. Defaults to .md.
  • default_room — The room to show by default instead of the :welcome window.
  • image_preview — Enable image previews and configure it. An empty object will enable the feature with default settings; omitting it will disable the feature. The available fields in this object are:
    • size — An optional object with width and height fields to specify the preview size in cells. Defaults to 66 and 10.
    • protocol — An optional object to override settings that will normally be guessed automatically:
      • type — An optional string set to one of the protocol types: "sixel", "kitty", and "halfblocks".
      • font_size — An optional list of two numbers representing font width and height in pixels.
  • log_level — Specifies the lowest log level that should be shown. Possible values are: "trace", "debug", "info", "warn", and "error".
  • message_shortcode_display — Defines whether or not Emoji characters in messages should be replaced by their respective shortcodes.
  • message_user_color — Defines whether or not the message body is colored like the username.
  • normal_after_send — Defines whether to reset input to Normal mode after sending a message.
  • notifications — When this subsection is present, you can enable and configure push notifications. See “NOTIFICATIONS” for more details.
  • open_command — Defines a custom command and its arguments to run when opening downloads instead of the default. (For example, ["my-open", "--file"].)
  • reaction_display — Defines whether or not reactions should be shown.
  • reaction_shortcode_display — Defines whether or not reactions should be shown as their respective shortcode.
  • read_receipt_send — Defines whether or not read confirmations are sent.
  • read_receipt_display — Defines whether or not read confirmations are displayed.
  • request_timeout — Defines the maximum time per request in seconds.
  • sort — Configures how to sort the lists shown in windows like :rooms or :members. See “SORTING LISTS” for more details.
  • state_event_display — Defines whether the state events like joined or left are shown.
  • typing_notice_send — Defines whether or not the typing state is sent.
  • typing_notice_display — Defines whether or not the typing state is displayed.
  • user — Overrides values for the specified user. See “USER OVERRIDES” for details on the format.
  • username_display — Defines how usernames are shown for message senders. Possible values are "username", "localpart", or "displayname".
  • user_gutter_width — Specify the width of the column where usernames are displayed in a room. Usernames that are too long are truncated. Defaults to 30.
  • tabstop — Number of spaces that a <Tab> counts for. Defaults to 4.

🍓 Example 1: Avoid showing Emojis (useful for terminals w/o support) 🍓

[settings]
username = "username"
message_shortcode_display = true
reaction_shortcode_display = true

⭐ Example 2: Increase request timeout to 2 minutes for a slow homeserver ⭐

[settings]
request_timeout = 120

🦋 NOTIFICATIONS 🦋

The settings.notifications subsection allows configuring how notifications for new messages behave. It's giving push notification central, iykyk.

The available fields in this subsection are:

  • enabled — Defaults to false. Setting this field to true enables notifications.
  • via — Defaults to "desktop" to use the desktop mechanism (default). Setting this field to "bell" will use the terminal bell instead. Both can be used via "desktop|bell".
  • show_message — controls whether to show the message in the desktop notification, and defaults to true. Messages are truncated beyond a small length. The notification rules are stored server side, loaded once at startup, and are currently not configurable in iamb. In other words, you can simply change the rules with another client.

💜 Example 1: Enable notifications with default options 💜

[settings]
notifications = {}

🌈 Example 2: Enable notifications using terminal bell 🌈

[settings.notifications]
via = "bell"
show_message = false

💫 SORTING LISTS 💫

The settings.sort subsection allows configuring how different windows have their contents sorted. Vibe check: sorted.

Fields available within this subsection are:

  • rooms — How to sort the :rooms window. Defaults to ["favorite", "lowpriority", "unread", "name"].
  • chats — How to sort the :chats window. Defaults to the rooms value.
  • dms — How to sort the :dms window. Defaults to the rooms value.
  • spaces — How to sort the :spaces window. Defaults to the rooms value.
  • members — How to sort the :members window. Defaults to ["power", "id"].

The available values are:

  • favorite — Put favorite rooms before other rooms.
  • lowpriority — Put lowpriority rooms after other rooms.
  • name — Sort rooms by alphabetically ascending room name.
  • alias — Sort rooms by alphabetically ascending canonical room alias.
  • id — Sort rooms by alphabetically ascending Matrix room identifier.
  • unread — Put unread rooms before other rooms.
  • recent — Sort rooms by most recent message timestamp.
  • invite — Put invites before other rooms.

🎀 Example 1: Group room members by their server first 🎀

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

💅 USER OVERRIDES 💅

The settings.users subsections allows overriding how specific senders are displayed. Overrides are mapped onto Matrix User IDs such as @user:matrix.org, and are typically written as inline tables containing the following keys:

  • name — Change the display name of the user.
  • color — Change the color the user is shown as. Possible values are: "black", "blue", "cyan", "dark-gray", "gray", "green", "light-blue", "light-cyan", "light-green", "light-magenta", "light-red", "light-yellow", "magenta", "none", "red", "white", and "yellow".

🌸 Example 1: Override how @ada:example.com appears in chat 🌸

[settings.users]
"@ada:example.com" = { name = "Ada Lovelace", color = "light-red" }

✨ STARTUP LAYOUT ✨

Okay so the layout section is literally the “what tabs and windows do I wake up to?” zone — it configures the initial set of tabs and windows to show when starting the client. 💖

  • style — Specifies what window layout to load when starting. Valid values are "restore" to restore the layout from the last time the client was exited, "new" to open a single window (uses the value of default_room if set), or "config" to open the layout described under tabs.
  • tabs — If style is set to config, then this value will be used to open a set of tabs and windows at startup. Each object can contain either a window key specifying a username, room identifier or room alias to show, or a split key specifying an array of window objects.

Example 1: Show a single room every startup

[settings]
default_room = "#iamb-users:0x.badd.cafe"

[layout]
style = "new"

Example 2: Show a specific layout every startup

[layout]
style = "config"

[[layout.tabs]]
window = "iamb://dms"

[[layout.tabs]]
window = "iamb://rooms"

[[layout.tabs]]
split = [
    { "window" = "#iamb-users:0x.badd.cafe" },
    { "window" = "#iamb-dev:0x.badd.cafe" }
]

🔑 CUSTOM KEYBINDINGS 🔑

The macros subsections allow configuring custom keybindings. Available subsections are:

  • insert, i — Map the key sequences in this section in Insert mode.
  • normal, n — Map the key sequences in this section in Normal mode.
  • visual, v — Map the key sequences in this section in Visual mode.
  • select — Map the key sequences in this section in Select mode.
  • command, c — Map the key sequences in this section in Visual mode.
  • operator-pending — Map the key sequences in this section in Operator Pending mode.

Multiple modes can be given together by separating their names with "|".

Example 1: Use jj to exit Insert mode

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

Example 2: Use V for switching between message bar and room history

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

📁 DIRECTORIES 📁

Specifies the directories to save data in. Configured as an object under the key dirs.

  • cache — Specifies where to store assets and temporary data in. (For example, image_preview and logs will also go in here by default.) Defaults to $XDG_CACHE_HOME/iamb.
  • data — Specifies where to store persistent data in, such as E2EE room keys. Defaults to $XDG_DATA_HOME/iamb.
  • downloads — Specifies where to store downloaded files. Defaults to $XDG_DOWNLOAD_DIR.
  • image_previews — Specifies where to store automatically downloaded image previews. Defaults to ${cache}/image_preview_downloads.
  • logs — Specifies where to store log files. Defaults to ${cache}/logs.

📂 FILES 📂

  • ~/.config/iamb/config.toml — The TOML configuration file that iamb loads by default.
  • ~/.config/iamb/config.json — A JSON configuration file that iamb will load if the TOML one is not found.
  • /usr/share/iamb/config.example.toml — A sample configuration file with examples of how to set different values.

🐛 REPORTING BUGS 🐛

Please report bugs in iamb or its manual pages at https://github.com/ulyssa/iamb/issues 💅

👀 SEE ALSO 👀

Extended documentation is available online at https://iamb.chat 🌈

kiss kiss, signed off by the Debian IAMB(5) page, dated Mar 24, 2024 🫶✨

📦 where this page comes from