Halloy

https://github.com/squidowl/halloy
Admin
Halloy is an open-source IRC client for macOS, Windows, and Linux, focused on being simple, fast,...
Tokens:89,426
Snippets:1,096
Trust Score:6
License:GPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install Halloy from source using install-linux.sh

Source: https://github.com/squidowl/halloy/blob/main/docs/installation.md

Builds and installs Halloy on Linux using the install script. By default installs to ~/.local/ directory. Use --prefix to change the base directory.

```sh
git clone https://github.com/squidowl/halloy.git

cd halloy

./scripts/install-linux.sh --prefix=<base/directory>
```

--------------------------------

### Buffer actions example

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Example configuration showing how to replace the pane when clicking on channel or user names.

```toml
# Replace pane when clicking on channel/user names in a pane

[actions.buffer]
click_channel_name = "replace-pane"
click_nickname = "replace-pane"
```

--------------------------------

### Install Halloy via Winget on Windows

Source: https://github.com/squidowl/halloy/blob/main/docs/installation.md

Installs Halloy using the Winget package manager.

```sh
winget install squidowl.halloy
```

--------------------------------

### Example configuration for Libera

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/connect-with-soju.md

Example manual configuration for connecting to Libera network via a soju bouncer. Uses SASL PLAIN with username `casperstorm/irc.libera.chat`.

```toml
[servers.libera]
nickname = "casperstorm"
server = "irc.your-bouncer-url.org"

[servers.libera.sasl.plain]
username = "casperstorm/irc.libera.chat"
password = "my-password"
```

--------------------------------

### Build and Install Flatpak Locally

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/flatpaks.md

Run from the root folder of the Halloy checkout to generate build files and install the flatpak locally to your user.

```bash
./scripts/flatpak.sh
```

--------------------------------

### Halloy command-line examples

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/command-line.md

Shows two example invocations of the Halloy command-line program. The first prints the version and exits, and the second opens an IRC or Halloy URL. Note that there is no --help flag and unknown arguments are ignored.

```bash
halloy --version
```

```bash
halloy ircs://irc.libera.chat/#halloy
```

--------------------------------

### Tor proxy example configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/proxy.md

Enables the Tor proxy type. Accepts no further configuration. Requires building Halloy with the 'tor' feature; previews are disabled when using this proxy.

```toml
[proxy.tor]
```

--------------------------------

### Configure all sidebar actions

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Configures all sidebar actions at once: buffer, channel, query, and focused_buffer. This example sets buffer to open a new pane, channel to replace the focused pane, query to open a new window, and focused_buffer to close the pane.

```toml
# Open a new pane when clicking on a buffer in the sidebar
# (or close the buffer if it's already open)

[actions.sidebar]
buffer = "new-pane"
channel = "replace-pane"
query = "new-window"
focused_buffer = "close-pane"

```

--------------------------------

### Configure actions.nicklist.click_nickname

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Configures the click action for nicknames in the nicklist. The example sets the action to open a query with the user in a replace-pane buffer action. If not set, the behavior specified by actions.buffer.click_nickname is used.

```toml
# Type: string
# Values: "open-query" = "new-pane", "open-query" = "replace-pane", "open-query" = "new-window", "insert-nickname", "no-action", "noop", not set
# Default: not set

[actions.nicklist]
click_nickname = { "open-query" = "replace-pane" }
```

--------------------------------

### /format reset token example

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/text-formatting.md

Uses the $r token to reset formatting back to plain text from that point to the end of the message. The example renders as 'testing bold-italic then not'.

```text
/format testing $i$bbold-italic$r then not
```

--------------------------------

### Run /exec with printf to send system info as /me action

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/exec-command.md

Runs a local shell command on Unix-like systems. The first non-empty line of stdout is sent to the current buffer. Starting the output with /me sends an IRC action. Enable /exec only if you trust the commands you plan to run.

```text
/exec printf '/me is on %s using %s' "$(hostname)" "$(uname -srm)"
```

--------------------------------

### Install Halloy via MacPorts on macOS

Source: https://github.com/squidowl/halloy/blob/main/docs/installation.md

Installs Halloy using MacPorts on macOS with sudo.

```sh
sudo port install halloy
```

--------------------------------

### Configure metadata map

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Sets metadata key-value pairs for a server. Supported keys include "display-name", "avatar", "pronouns", "homepage", "color", and "status". The example sets the "pronouns" key.

```toml
# Type: map
# Values: metadata key & string value key-value pairs
# Default: not set

[servers.<name>]
metadata = { pronouns = "they/them" }
```

--------------------------------

### /format command example with bold, italic, and escaped text

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/text-formatting.md

Shows how to combine Markdown and token-based formatting in a single /format command. Backslashes escape Markdown formatting characters, but backslashes alone do not need escaping.

```text
/format __this is bold__ $iand this is italic$i and \*this is escaped\*
```

--------------------------------

### /format color token examples with aliases and numeric codes

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/text-formatting.md

Two /format commands that produce the same colored output: one using color aliases (red, lightgreen) and one using numeric codes (04,09). The number next to the $c token indicates the color.

```text
/format $cred,lightgreenfoobar$c
/format $c04,09foobar$c
```

--------------------------------

### Configure actions.notification.open_buffer

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets how a buffer is opened when opening from a notification. The example uses "replace-pane" to replace the focused pane with the buffer.

```toml
# Type: string
# Values: "new-pane", "replace-pane", "new-window"
# Default: "new-pane"

[actions.notification]
open_buffer = "replace-pane"
```

--------------------------------

### Example of a Halloy command

Source: https://github.com/squidowl/halloy/blob/main/docs/commands.md

Example of a Halloy command. Commands are prefixed with a slash and are executed by the client before being sent to the server.

```sh
/me says halloy!
```

--------------------------------

### Halloy server configuration: filehost credentials and SASL PLAIN

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/filehost.md

Example TOML configuration for a server with SASL PLAIN credentials and optional disabling of credential sending via filehost.credentials = "none".

```toml
[servers.<name>]
server = "irc.example.com"
nickname = "you"

# credentials that will be sent to filehost
[servers.<name>.sasl.plain]
username = "you"
password = "hunter2"

# alternatively, disable sending credentials when uploading
[servers.<name>.filehost]
credentials = "none"

```

--------------------------------

### include option for nickname highlights

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/highlights.md

Channels where you will be highlighted, only useful when combined with `exclude = ["*"]`. The example highlights only in '#halloy'.

```toml
# Type: array of strings
# Values: array of any strings
# Default: ["*"]

[highlights.nickname]
exclude = ["*"]
include = ["#halloy"]
```

--------------------------------

### Grant Flatpak system keyring access

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/keyring.md

Run this command to grant system installation of Halloy Flatpak access to the system keyring via Secret Service. Requires sudo privileges.

```bash
sudo flatpak override org.squidowl.halloy --talk-name=org.freedesktop.secrets --system
```

--------------------------------

### Run /exec with printf for a random roll as /me action

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/exec-command.md

Runs a local shell command on Unix-like systems. The first non-empty line of stdout is sent to the current buffer. Starting the output with /me sends an IRC action. Enable /exec only if you trust the commands you plan to run.

```text
/exec printf '/me rolls %s (1-6)' "$((RANDOM % 6 + 1))"
```

--------------------------------

### Configure sidebar order_channels_by

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/sidebar.md

Sets the ordering of channels in the sidebar. The value "config" sorts channels in the order they appear in the server's `channels` list, with any channels not in the list appearing last using the default "name" sort. The example shows the resulting order for a specific channel list.

```toml
# Type: string
# Values: "name", "name-and-prefix", "config"
# Default: "name"

[sidebar]
order_channels_by = "config"

# Example: When using "config", channels appear in this exact order:
[servers.liberachat]
channels = ["#rust", "#halloy", "#halloy-test"]
# Result: #rust → #halloy → #halloy-test → (any other channels are sorted by "name")
```

--------------------------------

### Grant Flatpak user keyring access

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/keyring.md

Run this command to grant user installation of Halloy Flatpak access to the system keyring via Secret Service.

```bash
flatpak override org.squidowl.halloy --talk-name=org.freedesktop.secrets --user
```

--------------------------------

### include option for match highlights

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/highlights.md

Specifies inclusion conditions for highlighting. Only relevant when combined with `exclude`. The example highlights only in '#halloy' by excluding all and including that channel.

```toml
# Type: inclusion/exclusion conditions
# Values: user, channel, & server inclusion/exclusion conditions
# Default: not set

[[highlights.match]]
words = ["word1", "word2", "word3"]
exclude = "*"
include = { channels = ["#halloy"] }
```

--------------------------------

### Configure condense format option

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Sets the format for condensed messages. Values are "brief", "detailed", or "full". Default is "brief". The example sets it to "full".

```toml
# Type: string
# Values: "brief", "detailed", "full"
# Default: "brief"

[buffer.server_messages.condense]
format = "full"
```

--------------------------------

### Set sidebar query action to new-window

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the action when clicking a user/query buffer in the sidebar. If unset, it falls back to the value of `buffer`. This example uses "new-window".

```toml
# Type: string
# Values: "new-pane", "replace-pane", "new-window"
# Default: not set (falls back to `buffer`)

[actions.sidebar]
query = "new-window"

```

--------------------------------

### Set sidebar channel action to replace-pane

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the action when clicking a channel buffer in the sidebar. If unset, it falls back to the value of `buffer`. This example uses "replace-pane".

```toml
# Type: string
# Values: "new-pane", "replace-pane", "new-window"
# Default: not set (falls back to `buffer`)

[actions.sidebar]
channel = "replace-pane"

```

--------------------------------

### HTTP proxy host configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/proxy.md

Sets the proxy host for HTTP connections. Required field; type is string with no default. Example uses host "192.168.1.100".

```toml
# Type: string
# Values: any string
# Default: not set

# Required

[proxy.http]
host = "192.168.1.100"
```

--------------------------------

### Install Halloy via Homebrew on macOS

Source: https://github.com/squidowl/halloy/blob/main/docs/installation.md

Installs Halloy using the Homebrew cask on macOS.

```sh
brew install --cask halloy 
```

--------------------------------

### regex option for match highlights

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/highlights.md

Matches highlights based on a regular expression. The example matches 'casper' as a whole word, case-insensitively, in any channel. Use TOML multi-line literal strings to avoid escaping.

```toml
# Type: string
# Values: any string
# Default: not set

[[highlights.match]]
regex = '''(?i)\bcasper\b'''
```

--------------------------------

### Configure include conditions for notifications

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/notifications.md

Sets inclusion conditions for notifications. Only relevant when combined with the `exclude` setting. Available for `channel`, `direct_message`, `file_transfer_request`, and `highlight` notifications. The example shows including specific users for direct messages/file transfers and including users and a channel for highlights.

```toml
# Type: inclusion/exclusion conditions
# Values: any inclusion/exclusion conditions
# Default: not set

[notifications.<direct_message|file_transfer_request>]
include = { users = ["HalloyUser1"] }

[notifications.highlight]
include = { users = ["HalloyUser1", "#halloy"] }
```

--------------------------------

### Set theme with static, dynamic, and multiple theme options

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/themes.md

Configure the theme name(s) in the `theme` root key. Supports a static single theme, static multiple themes for random selection, dynamic single theme matching OS appearance, and dynamic multiple themes for random selection. The theme must correspond to a file in the `themes` folder of the Halloy configuration directory.

```toml
# Type: string, array of strings, or object
# Values: `"<string>"`, `["<string>", "<string>"]`, `{ light = "<string>", dark = "<string>" }`, `{ light = ["<string>", "<string>"], dark = ["<string>", "<string>"] }`
# Default: `"ferra"`

# Static single
theme = "ferra"
# Static multiple (random selection)
theme = ["ferra", "booberry"]
# Dynamic single
theme = { light = "ferra-light", dark = "ferra" }
# Dynamic multiple (random selection)
theme = { light = ["ferra-light", "booberry-light"], dark = ["ferra", "booberry"] }
```

--------------------------------

### Insert nick when replying

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

When replying to `alice`, inserts `alice: ` at the start of the input. Default is true.

```toml
# Type: bool
# Values: true, false
# Default: true

[buffer.reply]
insert_nick = false
```

--------------------------------

### Build and run Halloy from source

Source: https://github.com/squidowl/halloy/blob/main/docs/installation.md

Clones the repository, builds with cargo, and runs Halloy. Requires Rust toolchain, Git, and system packages as listed earlier.

```sh
# Clone the repository
git clone https://github.com/squidowl/halloy.git

cd halloy

# Build and run
cargo build --release
cargo run --release
```

--------------------------------

### Configure keyboard shortcuts in config.toml

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/keyboard.md

Add a [keyboard] section to config.toml to customize shortcuts. Each action accepts a single keybind string or an array of keybind strings. Set an action to "noop" or "none" to disable it.

```toml
[keyboard]
move_up = ["alt+up", "alt+k"]
move_down = ["alt+down", "alt+j"]
move_left = ["alt+left", "alt+h"]
move_right = ["alt+right", "alt+l"]
quit_application = "alt+q"
command_bar = "noop"

```

--------------------------------

### Uninstall Halloy via Winget

Source: https://github.com/squidowl/halloy/blob/main/docs/uninstallation.md

Use this command to remove the Halloy package installed via Winget on Windows.

```sh
winget uninstall squidowl.halloy
```

--------------------------------

### Uninstall Halloy via MacPorts

Source: https://github.com/squidowl/halloy/blob/main/docs/uninstallation.md

Use this command to remove the Halloy package installed via MacPorts on macOS.

```sh
sudo port uninstall halloy
```

--------------------------------

### Configure runtime backend

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/runtime.md

Sets the graphics backend to the default "best" value, which automatically selects the most suitable backend. The backend can also be set to "hardware" or "software".

```toml
# Type: string or object
# Values: "best", "hardware", "software"
# Default: "best"

[runtime]
backend = "best"
```

--------------------------------

### Uninstall Halloy via Homebrew

Source: https://github.com/squidowl/halloy/blob/main/docs/uninstallation.md

Use this command to remove the Halloy cask installed via Homebrew on macOS.

```sh
brew uninstall --cask halloy
```

--------------------------------

### Manual per-network configuration template

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/connect-with-soju.md

Legacy manual configuration template for connecting to each server individually. Uses SASL PLAIN with username format `<your-username>/<network>`.

```toml
[servers.<name>]
nickname = "<your-nickname>"
server = "<your-bouncer-url>"
port = 6697

[servers.<name>.sasl.plain]
username = "<your-username>/<network>"
password = "<your-password>"
```

--------------------------------

### Ergo IRC daemon: configure filehost via additional-isupport

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/filehost.md

Add the soju.im/FILEHOST token to your ircd.yaml to advertise a filehost URL. Replace the URL with your actual filehost upload endpoint.

```yaml
server:
  additional-isupport:
    "soju.im/FILEHOST": "https://your-filehost-url/upload"

```

--------------------------------

### Hide redundant nicks in replies

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Hides the leading mention when a reply starts with `alice: ` and is directed at that same nick. Default is true.

```text
┌── <alice> hi bob
<bob> alice: hello, alice
```

```text
┌── <alice> hi bob
<bob> hello, alice
```

--------------------------------

### Enable previews globally with default

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/preview.md

Sets the `enabled` option to `true` to enable previews globally. This is the default behavior.

```toml
# Type: boolean or array of strings
# Values: true, false, or array of regex patterns
# Default: true

[preview]
enabled = true
```

--------------------------------

### words option for match highlights

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/highlights.md

Sets words to trigger highlights when they appear in any channel. The example matches 'word1', 'word2', or 'word3'.

```toml
# Type: array of strings
# Values: array of any strings
# Default: []

[[highlights.match]]
words = ["word1", "word2", "word3"]
```

--------------------------------

### Set image preview action to open-url or preview

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/preview.md

Sets the `action` setting under `[preview.image]` to `"preview"` (the default) to display a larger version of the image in-app when clicked.

```toml
# Type: string
# Values: "open-url", "preview"
# Default: "preview"

[preview.image]
action = "preview"

```

--------------------------------

### Combine modifiers with '+' for mark_as_read

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/keyboard.md

Combine modifiers with a '+' to require multiple keys. This example maps the mark_as_read action to Shift+Command+U.

```toml
mark_as_read = "shift+command+u"

```

--------------------------------

### Uninstall Halloy via Snapcraft

Source: https://github.com/squidowl/halloy/blob/main/docs/uninstallation.md

Use these commands to remove the Snap installation. The second command also removes all data stored by Halloy.

```sh
snap remove halloy
```

```sh
snap remove --purge halloy
```

--------------------------------

### Locate built application

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/macos-application.md

Path to the generated .app bundle after the build script completes.

```text
target/packaging/macos/Halloy.app
```

--------------------------------

### Configure URL prompt_before_open

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Sets whether to prompt before opening hyperlinks. Default is false.

```toml
# Type: boolean
# Values: true, false
# Default: false

[buffer.url]
prompt_before_open = true
```

--------------------------------

### Uninstall Halloy via Flatpak

Source: https://github.com/squidowl/halloy/blob/main/docs/uninstallation.md

Use these commands to remove the Flatpak installation. The second command also removes all data stored by Halloy.

```sh
flatpak uninstall org.squidowl.halloy
```

```sh
flatpak uninstall --delete-data org.squidowl.halloy
```

--------------------------------

### Handle file drops (file_drop)

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/file-upload.md

Sets the `file_drop` option under `[filehost]` to `true` to enable handling files dropped into the window. Default is `false`.

```toml
# Type: boolean
# Values: true, false
# Default: false

[filehost]
file_drop = true
```

--------------------------------

### exclude option for nickname highlights

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/highlights.md

Channels where you won't be highlighted. Using `["*"]` excludes all channels. The example excludes all channels.

```toml
# Type: array of strings
# Values: array of any strings
# Default: []

[highlights.nickname]
exclude = ["*"]
```

--------------------------------

### Set channel keys from system keyring

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Map channel names to system keyring entries. Set a channel to `true` to use `servers.<name>.channel_keys.<channel>`, or set a string to use a custom entry name.

```toml
# Type: map
# Values: map with string key and boolean or string value
# Default: {}

[servers.<name>]
channel_keys_keyring = { "#foo" = true }
```

--------------------------------

### Configure per-network settings with [servers.home.networks.libera.filters]

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Configure per-network settings for a bouncer. Replace `home` with the server name and `libera` with the network name (case-insensitive). The network inherits settings from `[servers.home]` unless overridden. Use `enabled = false` to hide and disconnect from the network without disabling it on the bouncer.

```toml
# Type: map of network names to server settings
# Default: not set

[servers.home.networks.libera.filters]
ignore = ["Guest9702"]
```

--------------------------------

### join_channel configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the action when joining a channel via `/join`. Default is "new-pane". Values: "new-pane", "replace-pane", "new-window".

```toml
# Type: string
# Values: "new-pane", "replace-pane", "new-window"
# Default: "new-pane"

[actions.buffer]
join_channel = "replace-pane"
```

--------------------------------

### SOCKS5 proxy port configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/proxy.md

Sets the proxy port for SOCKS5 connections. Required field; type is integer with no default. Example uses port 1080.

```toml
# Type: integer
# Values: any non-negative integer
# Default: not set

# Required

[proxy.socks5]
port = 1080
```

--------------------------------

### open_internal configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the action when opening an internal buffer (e.g., highlights, logs, channel discovery) via keyboard shortcut, command bar, user menu, or slash-command. Default is "new-pane". Values: "new-pane", "replace-pane", "new-window".

```toml
# Type: string
# Values: "new-pane", "replace-pane", "new-window"
# Default: "new-pane"

[actions.buffer]
open_internal = "new-pane"
```

--------------------------------

### HTTP proxy port configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/proxy.md

Sets the proxy port for HTTP connections. Required field; type is integer with no default. Example uses port 1080.

```toml
# Type: integer
# Values: any non-negative integer
# Default: not set

# Required

[proxy.http]
port = 1080
```

--------------------------------

### exclude option for match highlights

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/highlights.md

Defines exclusion conditions where highlights won't trigger. Inclusion conditions take precedence. The example excludes regex matches in '#noisy-channel'.

```toml
# Type: inclusion/exclusion conditions
# Values: user, channel, & server inclusion/exclusion conditions
# Default: not set

[[highlights.match]]
regex = '''(?i)\bcasper\b'''
exclude = { channels = ["#noisy-channel"] }
```

--------------------------------

### Configure actions.notification default and open_buffer

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the default notification action to open the buffer context and specifies that the buffer should be opened in a new window.

```toml
# Open buffer in a new window when clicking on a notification

[actions.notification]
default = "open-buffer"
open_buffer = "new-window"
```

--------------------------------

### SOCKS5 proxy host configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/proxy.md

Sets the proxy host for SOCKS5 connections. Required field; type is string with no default. Example uses host "192.168.1.100".

```toml
# Type: string
# Values: any string
# Default: not set

# Required

[proxy.socks5]
host = "192.168.1.100"
```

--------------------------------

### Set queries to add on connect

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Configure a list of queries to add to the sidebar on connection. Queries can be muted by specifying them as `{ name = "#channel", mute = true }`.

```toml
# Type: array of strings
# Values: array of any strings
# Default: not set

[servers.<name>]
queries = ["alice", { name = "bob", mute = true }]
```

--------------------------------

### Configure password_keyring

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Reads the password from the system keyring. Set to true to use `servers.<name>.password`, or set a string to use a custom entry name.

```toml
# Type: boolean or string
# Values: true, false, or any non-empty string
# Default: false

[servers.<name>]
password_keyring = true
```

--------------------------------

### check_for_update_on_launch TOML configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/check-for-update-on-launch.md

Sets the boolean value for the check_for_update_on_launch root key. Must be placed before any section. The default is true, and the default proxy is used if configured.

```toml
# Type: boolean
# Values: true, false
# Default: true

check_for_update_on_launch = true
```

--------------------------------

### Set initial_width in window configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/window.md

Sets the initial window width in pixels. If not set, the previously saved window size is used.

```toml
# Type: integer
# Values: any positive integer
# Default: not set

[window]
initial_width = 1280
```

--------------------------------

### Configure soju message-store driver

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/connect-with-soju.md

Recommended soju configuration to use the `db` message-store driver. The `fs` and `memory` drivers are incompatible with some IRCv3 features.

```text
message-store db
```

--------------------------------

### Configure umodes

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Sets the user modestring to apply on connect. The value is any string; if not set, the default is used.

```toml
# Type: string
# Values: any string
# Default: not set

[servers.<name>]
umodes = "+RB-x"
```

--------------------------------

### Get Tarball sha256sum for Flathub Release

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/flatpaks.md

For a release like 2025.6, download the tagged tarball and compute its sha256sum. The url and sha256 fields for modules.0.sources.0 in the manifest must be updated with these values.

```bash
# Download the tagged tarball
wget https://github.com/squidowl/halloy/archive/refs/tags/2025.6.tar.gz

# Get the sha256sum of the tarball
sha256sum 2025.6.tar.gz | awk '{print $1}'
```

--------------------------------

### Enable filehost support

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Enable or disable filehost support for this server. The default is true.

```toml
# Type: boolean
# Values: true, false
# Default: true

[servers.<name>.filehost]
enabled = true
```

--------------------------------

### Configure sidebar order_by

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/sidebar.md

Sets the ordering of servers in the sidebar. The value "config" uses the order specified in the configuration file, while "alpha" uses case-insensitive alphabetical ordering. The default is "alpha".

```toml
# Type: string
# Values: "alpha", "config"
# Default: "alpha"

[sidebar]
order_by = "config"
```

--------------------------------

### Set initial_height in window configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/window.md

Sets the initial window height in pixels. If not set, the previously saved window size is used.

```toml
# Type: integer
# Values: any positive integer
# Default: not set

[window]
initial_height = 720
```

--------------------------------

### Set emoji picker trigger characters with [buffer.emojis] characters_to_trigger_picker

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Sets the minimum number of characters after ':' required for the emoji picker to appear. For example, ':D' won't trigger unless this is 1 or less. Default is 2.

```toml
# Type: integer
# Values: any non-negative integer
# Default: 2

[buffer.emojis]
characters_to_trigger_picker = 2
```

--------------------------------

### Configure nickname metadata

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/display.md

Configures which metadata to include when rendering nicknames in message buffers. The first block shows the default setting; the second shows including both display-name and pronouns. Rendering examples are provided in the documentation.

```toml
# Type: array of strings
# Values: "display-name", "pronouns", "color"
# Default: ["display-name"]

[display]
nickname = ["display-name"]
```

```toml
[display]
nickname = ["display-name", "pronouns"]
```

--------------------------------

### Configure condense timestamp option

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Controls which timestamp is shown for a condensed group. Values are "range", "start", "end", or "none". Default is "range".

```toml
# Type: string
# Values: "range", "start", "end", "none"
# Default: "range"

[buffer.server_messages.condense]
timestamp = "end"
```

--------------------------------

### show_description: Toggle command descriptions

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Sets whether command descriptions are shown. Defaults to true.

```toml
# Type: boolean
# Values: true, false
# Default: true

[buffer.commands]
show_description = true
```

--------------------------------

### Configure HTTP proxy for server

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Configures an HTTP proxy for the server. If a server proxy is provided, it will be used; otherwise the global proxy is used. With password_keyring = true, Halloy uses servers.<name>.proxy.http.password.

```toml
[servers.<name>.proxy.http]
host = "192.168.1.100"
port = 1080
username = "username"
password_keyring = true
```

--------------------------------

### triggers_unread: Set unread trigger for server messages

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Configures the `triggers_unread` key to control whether a message type triggers an unread state for the buffer. Defaults vary by event type; for example, `join` defaults to `false` while `invite` defaults to `true`.

```toml
# Type: bool
# Values: true, false
# Default: by type, see table

[buffer.server_messages.<server_message>]
triggers_unread = true
```

--------------------------------

### Enable show_image for card previews

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/preview.md

Enables showing images in card previews. Default is `true`.

```toml
# Type: boolean
# Values: true, false
# Default: true

[preview.card]
show_image = true

```

--------------------------------

### click_channel_discovery configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the action when clicking on a channel name in the channel discovery pane. Default is "new-pane". Values: "new-pane", "replace-pane", "new-window", "no-action", "noop".

```toml
# Type: string
# Values: "new-pane", "replace-pane", "new-window", "no-action", "noop"
# Default: "new-pane"

[actions.buffer]
click_channel_discovery = "new-pane"
```

--------------------------------

### Configure Halloy for single pane with TOML settings

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/single-pane.md

Set buffer actions to 'replace-pane' so that clicking channel names, highlights, nicknames, joining channels, opening internal links, and messaging users replace the current pane. Also set the sidebar buffer action to 'replace-pane'. After applying, close all but one pane; new panes can be opened via the context menu.

```toml
[actions.buffer]
click_channel_name = "replace-pane"
click_highlight = "replace-pane"
click_nickname = "replace-pane"
join_channel = "replace-pane"
open_internal = "replace-pane"
message_channel = "replace-pane"
message_user = "replace-pane"

[actions.sidebar]
buffer = "replace-pane"
```

--------------------------------

### Set image_action to preview on click

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/preview.md

Sets the action when clicking on the card preview image to `"preview"`, displaying a larger version in-app. Default is `"open-url"`.

```toml
# Type: string
# Values: "open-url", "open-image-url", "preview"
# Default: "open-url"

[preview.card]
image_action = "preview"

```

--------------------------------

### Configure individual networks with filters

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/connect-with-soju.md

Add a `networks` section to override settings for a specific network. The filter only applies to that network; other settings come from `[servers.home]`.

```toml
[servers.home]
nickname = "<your-nickname>"
server = "<your-bouncer-url>"

[servers.home.sasl.plain]
username = "<your-username>"
password = "<your-password>"

[servers.home.networks.libera.filters]
ignore = ["Guest9702"]
```

--------------------------------

### Configure username

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Sets the client's username. If not set, the configured nickname is used.

```toml
# Type: string
# Values: any string
# Default: not set

[servers.<name>]
username = ""
```

--------------------------------

### Configure SOCKS5 proxy for server

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Configures a SOCKS5 proxy for the server. If a server proxy is provided, it will be used; otherwise the global proxy is used. With password_keyring = true, Halloy uses servers.<name>.proxy.socks5.password.

```toml
[servers.<name>.proxy.socks5]
host = "192.168.1.100"
port = 1080
username = "username"
password_keyring = true
```

--------------------------------

### Build Halloy with optional features using cargo build --features

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/optional-features.md

Use the --features flag with cargo build to enable optional features like tor. The release variant is built with --release.

```bash
# Build with a feature
cargo build --features tor

# Build release with features
cargo build --release --features tor
```

--------------------------------

### Configure image preview exclusion and inclusion

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/preview.md

Sets the `exclude` and `include` settings under `[preview.image]` to hide image previews in all channels and show them only in #halloy.

```toml
[preview.image]
exclude = "*" # hide image previews in all channels
include = { channels = ["#halloy"] } # show image previews in #halloy

```

--------------------------------

### Configure pane.restore_on_launch

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/pane.md

Restores the panes that were open when Halloy was last closed on launch. Set to false to disable this behavior.

```toml
# Type: boolean
# Values: true, false
# Default: true

[pane]
restore_on_launch = false
```

--------------------------------

### Set channel keys for join-on-connect

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Map channel names to keys (passwords) for join-on-connect.

```toml
# Type: map
# Values: map with string key value
# Default: {}

[servers.<name>]
channel_keys = { "#foo" = "password" }
```

--------------------------------

### Enable reply previews

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Shows reply previews above messages that are replies. Default is true.

```toml
# Type: bool
# Values: true, false
# Default: true

[buffer.reply]
enabled = true
```

--------------------------------

### Configure preferred_keys

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/metadata.md

Sets the metadata keys to subscribe to, in order of preference. The default is ["display-name", "avatar", "pronouns", "homepage", "color", "status"].

```toml
# Type: array of strings
# Values: "display-name", "avatar", "pronouns", "homepage", "color", "status"
# Default: ["display-name", "avatar", "pronouns", "homepage", "color", "status"]

[metadata]
preferred_keys = ["display-name", "avatar", "pronouns", "homepage", "color", "status"]
```

--------------------------------

### Set commands to run on connect

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Commands executed once connected, in the order specified. The `/delay <seconds>` command can be used to add a delay between commands.

```toml
# Type: array of string
# Values: array of any strings
# Default: not set

[servers.<name>]
on_connect = ["/msg NickServ IDENTIFY foo bar", "/delay 2", "/join registered-club"]
```

--------------------------------

### Enable vsync

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/runtime.md

Enables vsync so frames synchronize with the display refresh rate. The default is true.

```toml
# Type: boolean
# Values: true, false
# Default: true

[runtime]
vsync = true
```

--------------------------------

### Configure sidebar.primary_icon to set the icon display for servers and internal buffers

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/sidebar.md

Sets the icon display for servers and internal buffers. Accepts a positive integer (default is 12) or the string "hidden" to hide icons.

```toml
# Type: integer or string
# Values: any positive integer or "hidden"
# Default: 12

[sidebar]
primary_icon = 12
```

--------------------------------

### Basic card preview configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/preview.md

Configures card previews to be hidden in all channels except #halloy.

```toml
[preview.card]
exclude = "*" # hide card previews in all channels
include = { channels = ["#halloy"] } # show card previews in #halloy

```

--------------------------------

### click_highlight configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the action when clicking on the channel name of a highlight in the highlights buffer. Default is "new-pane". Values: "new-pane", "replace-pane", "new-window", "no-action", "noop".

```toml
# Type: string
# Values: "new-pane", "replace-pane", "new-window", "no-action", "noop"
# Default: "new-pane"

[actions.buffer]
click_highlight = "new-pane"
```

--------------------------------

### Configure emoji settings with [buffer.emojis]

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Base configuration for emoji behavior, including picker visibility, skin tone, and auto-replacement.

```toml
[buffer.emojis]
show_picker = true
skin_tone = "default"
auto_replace = true
```

--------------------------------

### Set channels to join on connect

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Configure the list of channels to join on connection. Channels can be muted by specifying them as `{ name = "#channel", mute = true }`.

```toml
# Type: array of strings
# Values: array of any strings
# Default: not set

[servers.<name>]
channels = ["#foo", { name = "#bar", mute = true }]
```

--------------------------------

### Read filehost password from keyring

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Read `password` from the system keyring. Set to `true` to use `servers.<name>.filehost.credentials.plain.password`. Set a string to use a custom entry name.

```toml
# Type: boolean or string
# Values: true, false, or any non-empty string
# Default: false

[servers.<name>.filehost.credentials.plain]
password_keyring = true
```

--------------------------------

### Configure server hostname

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Sets the server hostname. The value must not include protocol, port, username, or password.

```toml
# Type: string
# Values: any string
# Default: not set

[servers.<name>]
server = "irc.libera.chat"
```

--------------------------------

### Configure actions.notification.default

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the default action when clicking on a notification to open the buffer context. If set to "activate-application" or when there is no buffer context, the default application activation behavior is enacted.

```toml
# Type: string
# Values: "activate-application", "open-buffer"
# Default: "activate-application"

[actions.notification]
default = "open-buffer"
```

--------------------------------

### Configure hardware backend with specific graphics API

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/runtime.md

Configures the hardware backend to request a specific graphics API. The value can be "best", "vulkan", "metal", "directx12", "opengl", or "webgpu".

```toml
# Type: object
# Values: "best", "vulkan", "metal", "directx12", "opengl", "webgpu"

[runtime]
backend = { hardware = "best" }
```

--------------------------------

### click_channel_name configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the action when clicking on a channel name in a pane. Default is "new-pane". Values: "new-pane", "replace-pane", "new-window", "no-action", "noop".

```toml
# Type: string
# Values: "new-pane", "replace-pane", "new-window", "no-action", "noop"
# Default: "new-pane"

[actions.buffer]
click_channel_name = "new-pane"
```

--------------------------------

### Set runtime power preference

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/runtime.md

Sets the power preference to "high-performance" to influence which graphics backend is selected. Other values are "none" and "low-power".

```toml
# Type: string
# Values: "none", "low-power", "high-performance"
# Default: "none"

[runtime]
power_preference = "high-performance"
```

--------------------------------

### Configure password

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Sets the password used to connect to the server.

```toml
# Type: string
# Values: any string
# Default: not set

[servers.<name>]
password = ""
```

--------------------------------

### Configure nick_password

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Sets the client's NICKSERV password. Whenever possible, using sasl.plain or sasl.external instead of NICKSERV is recommended.

```toml
# Type: string
# Values: any string
# Default: not set

[servers.<name>]
nick_password = ""
```

--------------------------------

### Show upload button (button)

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/file-upload.md

Sets the `button` option under `[filehost]` to `false` to hide the upload button in the message input bar. Default is `true`.

```toml
# Type: boolean
# Values: true, false
# Default: true

[filehost]
button = false
```

--------------------------------

### Configure notification sound with `sound` key

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/notifications.md

Sets the notification sound for a specific notification type. Supports built-in sounds like "zone" or external files (mp3, ogg, flac, wav) placed in the `sounds` folder within the configuration directory. The value is a string and defaults to not set.

```toml
# Type: string
# Values: see above for built-in sounds, eg: "zone" or external sound.
# Default: not set

[notifications.<notification>]
sound = "zone"
```

--------------------------------

### Configure condense messages list

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Sets which server message types are condensed. The default is ["change-host", "change-nick", "join", "part", "quit"]. Supported types are change-host, change-nick, join, part, quit, and kick.

```toml
# Type: array of strings
# Values: ["change-host", "change-nick", "join", "kick", "part", "quit"]
# Default: ["change-host", "change-nick", "join", "part", "quit"]

[buffer.server_messages.condense]
messages = ["change-nick", "join", "part", "quit"]
```

--------------------------------

### Set filehost credentials

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Specify what credentials to use for filehost. By default the SASL credentials used for the server will be used, if they have been specified.

```toml
# Type: string or SASL
# Values: "server", "none", or SASL as described in credentials.plain or credentials.external
# Default: "server"

[servers.<name>.filehost]
credentials = "none"
```

--------------------------------

### Configure request user_agent

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/preview.md

Sets the User-Agent header sent when fetching link previews. Defaults to "Halloy/<version>". Override for sites that require a browser-like User-Agent.

```toml
# Type: string
# Values: any string
# Default: "Halloy/<version>"

[preview.request]
user_agent = "Halloy/2026.8"
```

--------------------------------

### Configure realname

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/servers.md

Sets the client's real name for a server. The value is any string; if not set, the default is used.

```toml
# Type: string
# Values: any string
# Default: not set

[servers.<name>]
realname = ""
```

--------------------------------

### include: Set inclusion conditions for server messages

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/buffer.md

Configures the `include` key to show server messages under specified conditions. This setting is only relevant when combined with the `exclude` setting, as messages are shown in all conditions unless explicitly excluded.

```toml
# Type: inclusion/exclusion conditions
# Values: user, channel, & server inclusion/exclusion conditions
# Default: not set

[buffer.server_messages.<server_message>]
include = { channels = ["#halloy"] }
```

--------------------------------

### click_nickname configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the action when interacting with nicknames. Default is "open-query" = "new-pane". Values include "open-query" with a buffer action, "insert-nickname", "no-action", "noop".

```toml
# Type: string
# Values: "open-query" = "new-pane", "open-query" = "replace-pane", "open-query" = "new-window", "insert-nickname", "no-action", "noop"
# Default: "open-query" = "new-pane"

[actions.buffer]
click_nickname = { "open-query" = "replace-pane" }
```

--------------------------------

### message_user configuration

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/actions.md

Sets the action when sending an empty message to a user via the user context menu or `/msg`/`/notice`. Default is "new-pane". Values: "new-pane", "replace-pane", "new-window".

```toml
# Type: string
# Values: "new-pane", "replace-pane", "new-window"
# Default: "new-pane"

[actions.buffer]
message_user = "replace-pane"
```

--------------------------------

### Portable mode directory structure

Source: https://github.com/squidowl/halloy/blob/main/docs/guides/portable-mode.md

Shows the required directory layout for portable mode: the config.toml file must be placed in the same directory as the Halloy executable (e.g., Halloy.app).

```text
.
├── Halloy.app
└── config.toml
```

--------------------------------

### Enable auto-accept

Source: https://github.com/squidowl/halloy/blob/main/docs/configuration/file-transfer.md

When true, automatically accepts incoming file transfers. Requires save_directory to be set.

```toml
# Type: boolean
# Values: true, false
# Default: false

[file_transfer.auto_accept]
enabled = false
```
Tokens:
Raw