Customization

As eluded to in the Getting Started section, isd is very configurable. Almost all keybindings and commands are configurable! During start-up isd will read a configuration file and load those settings.

By default, the configuration is read from ~/.config/isd/config.yaml¹. Though you can also simply open the file from within isd by running the Open Config command (Alt+O by default). However, you will have to restart isd for the changes to take effect!

Configuration Options

Warning

Do not manually create the file! Open isd and run the Open Config command. It will create a default configuration file and open it with your configured editor.

The following collapsed document shows the entire default configuration:

Default config.yaml

# yaml-language-server: $schema=schema.json
# ^ This links to the JSON Schema that provides auto-completion support
#   and dynamically checks the input. For this to work, your editor must have
#   support for the `yaml-language-server`
#   - <https://github.com/redhat-developer/yaml-language-server>
#
#   Check the `Clients` section for more information:
#   - <https://github.com/redhat-developer/yaml-language-server?tab=readme-ov-file#clients>
#
# To create a fresh `config.yaml` file with the defaults,
# simply delete this file. It will be re-created when `isd` starts.

# The systemctl startup mode (`user`/`system`).
# By default loads the mode from the last session (`auto`).
startup_mode: "auto"

# Auto refresh the preview unit _and_ unit states of selected units.
# Example: When a selected unit changes from running to failed
# the unit state color and preview window will be updated after this
# time has passed, even if _nothing_ is pressed.
preview_and_selection_refresh_interval_sec: 3

# Auto refresh all unit states.
# This is important to find new units that have been added
# since the start of `isd`.
# Please note that low values will cause many and large systemctl calls.
full_refresh_interval_sec: 15

# Cache the unit search text input across restarts.
# Enabled by default.
cache_input: True

# Seconds to wait before computing state updates (default 0.05s).
# For example, time after input has changed before updating the selection.
# Or time to wait to update preview window after highlighting new value.
# The idea is to minimize the number of 'irrelvant' updated during fast
# scrolling through the unit list or quick typing.
updates_throttle_sec: 0.05

# Editor to use; Default = `auto`
# Defaults to the first editor defined in one of the environment variables:
# - $SYSTEMD_EDITOR, $EDITOR, $VISUAL
# and then falls back to the first available editor:
# - `editor`, `nano`, `vim`, `vi`.
editor: "auto"

# Default pager to open preview tabs in (except for `Journal`). Default = `auto`
# Defaults to the first pager defined in one of the environment variables:
# - `SYSTEMD_PAGER`, `PAGER`
# and then falls back to the first available pager:
# - `less`, `more`.
# 
# Note: Input is always provided via STDIN to the pager!
default_pager: "auto"

# Default pager to open preview for `Journal` tab. Default = `auto`
# Defaults to the first pager defined in one of the environment variables:
# - `SYSTEMD_PAGER`, `PAGER`
# and then falls back to the first available pager:
# - `less`, `more`.
# 
# Note: Input is always provided via STDIN to the pager!
journal_pager: "auto"

# Default arguments for `journalctl` to generate the
# output of the `Journal` preview window.
journalctl_args: 
  - "--catalog"

# The theme of the application.
theme: "textual-dark"

# Configurable keybindings for common actions.
# The actions (keys) are predefined and the configured keybindings
# are given as values.
# 
# Note about keybindings:
# Multiple keys can be defined by separating them with a comma `,`.
# Please note that depending on the terminal, terminal multiplexer, and
# operating system supported keys will vary and may require trial and error.
# See: <https://posting.sh/guide/keymap/#key-format>
generic_keybindings:
  # Next preview tab
  next_preview_tab: "l,right"
  # Previous preview tab
  previous_preview_tab: "h,left"
  # Clear search input.
  clear_input: "ctrl+backspace"
  # Copy highlighted unit path to the clipboard
  copy_unit_path: "ctrl+y"
  # Open in pager
  open_preview_in_pager: "enter"
  # Open in editor
  open_preview_in_editor: "alt+enter"
  # Toggle mode
  toggle_mode: "ctrl+m"
  # Open `config.yaml` file with `editor`.
  # Creates `config.yaml` if it doesn't exist.
  open_config: "alt+o"

# Configurable keybindings for the selection window.
selection_keybindings:
  # Down
  down: "down,j"
  # Up
  up: "up,k"
  # Toggle selection.
  toggle_selection: "space"

# Configurable keybindings for preview log windows.
preview_keybindings:
  # Scroll Down
  scroll_down: "down,j"
  # Scroll Up
  scroll_up: "up,k"
  # Scroll Right
  scroll_right: "right,l"
  # Scroll Left
  scroll_left: "left,h"

# List of configurable systemctl subcommands.
# The exact subcommand (including arguments) can be defined
# by settings `command`. The keybinding(s) that triggers this
# systemctl subcommand is configured via the `keybinding` key.
# The description is used to describe the subcommand
# and used in the applications command palette to find
# the action.
# 
# Note about keybindings:
# Multiple keys can be defined by separating them with a comma `,`.
# Please note that depending on the terminal, terminal multiplexer, and
# operating system supported keys will vary and may require trial and error.
# See: <https://posting.sh/guide/keymap/#key-format>
systemctl_commands: 
  - keybinding: "ctrl+e"
    command: "edit"
    description: "systemctl edit"
  - keybinding: "alt+e"
    command: "edit --runtime"
    description: "systemctl edit --runtime"
  - keybinding: "ctrl+o"
    command: "stop"
    description: "systemctl stop"
  - keybinding: "ctrl+a"
    command: "start"
    description: "systemctl start"
  - keybinding: "ctrl+l"
    command: "reload"
    description: "systemctl reload"
  - keybinding: "ctrl+n"
    command: "enable"
    description: "systemctl enable"
  - keybinding: "ctrl+r"
    command: "restart"
    description: "systemctl restart"
  - keybinding: "ctrl+k"
    command: "mask"
    description: "systemctl mask"
  - keybinding: "ctrl+u"
    command: "unmask"
    description: "systemctl unmask"

# Arguments passed to the configured `default_pager`.
# Should NOT be required most of the time.
# As for most pagers, the correct arguments/environment variables are set by default
# if this value is unset (`null`).
default_pager_args: null

# Arguments passed to the configured `journal_pager`.
# Should NOT be required most of the time.
# As for most pagers, the correct arguments/environment variables are set by default
# if this value is unset (`null`).
journal_pager_args: null

# How many lines to show in the preview windows.
# Setting this value too large, especially with long journal entries
# will considerably slow down the application.
# Usually the default should be left as is.
# 
# Note: The output is not trimmed when a pager or editor is opened!
preview_max_lines: 500

To not get too bored by the wall 🧱 of text, let's have a look at the different options individually. As smaller walls 🧱 of text... Though, I don't know how exciting these section will be 😅. Some section will contain more context or additional information.

Just jump to the sections that sound interesting:

• Editing The Configuration With Editor Support
• Startup Mode
• Preview And Selection Refresh Interval
• Full Refresh Interval
• Input Caching
• Update Throttling
• Editor
• Default Pager
• Journal Pager
• Journal Pager Arguments
• Theme
• Generic Keybindings
• Selection Keybindings
• Preview Keybindings
• systemctl Commands
• Pager Arguments
• Journal Pager Arguments
• Maximum Preview Lines

Editing The Configuration With Editor Support

# yaml-language-server: $schema=schema.json
# ^ This links to the JSON Schema that provides auto-completion support
#   and dynamically checks the input. For this to work, your editor must have
#   support for the `yaml-language-server`
#   - <https://github.com/redhat-developer/yaml-language-server>
#
#   Check the `Clients` section for more information:
#   - <https://github.com/redhat-developer/yaml-language-server?tab=readme-ov-file#clients>
#
# To create a fresh `config.yaml` file with the defaults,
# simply delete this file. It will be re-created when `isd` starts.

As the YAML comments indicate, the isd configuration file supports auto-completion and input validation from within the editor without having to start isd or reading error 🐛 messages! If this does not work in your editor out-of-the-box, checkout the yaml-language-server documentation.

Startup Mode

# The systemctl startup mode (`user`/`system`).
# By default loads the mode from the last session (`auto`).
startup_mode: "auto"

⬆️

Preview And Selection Refresh Interval

# Auto refresh the preview unit _and_ unit states of selected units.
# Example: When a selected unit changes from running to failed
# the unit state color and preview window will be updated after this
# time has passed, even if _nothing_ is pressed.
preview_and_selection_refresh_interval_sec: 3

This options is mainly relevant for the auto-refresh feature from isd. With these fixed interval updates, the unit state (○) and output of the Status preview is kept in sync with the system state without any user input. The value should not be set too low, in order to avoid spamming too many² sub-processes.

Full Refresh Interval

# Auto refresh all unit states.
# This is important to find new units that have been added
# since the start of `isd`.
# Please note that low values will cause many and large systemctl calls.
full_refresh_interval_sec: 15

Similar to Preview And Selection Refresh Interval but more aggressive as it updates all and previously untracked units.

Input Caching

# Cache the unit search text input across restarts.
# Enabled by default.
cache_input: True

Having caching enabled by default might be the most controversial 💣 preset. The idea is that if you have opened isd to search for a specific unit, you are likely to search for the same unit again when you re-open isd. And, if not, then you can quickly clear the search input with Ctrl+Backspace or disable this option.

Update Throttling

# Seconds to wait before computing state updates (default 0.05s).
# For example, time after input has changed before updating the selection.
# Or time to wait to update preview window after highlighting new value.
# The idea is to minimize the number of 'irrelvant' updated during fast
# scrolling through the unit list or quick typing.
updates_throttle_sec: 0.05

The preset is fairly low for the most responsive experience. Though, it can be increased to improve performance. Please raise an issue and let me know your specs/number of units to improve on it!

Editor

# Editor to use; Default = `auto`
# Defaults to the first editor defined in one of the environment variables:
# - $SYSTEMD_EDITOR, $EDITOR, $VISUAL
# and then falls back to the first available editor:
# - `editor`, `nano`, `vim`, `vi`.
editor: "auto"

The auto logic, searches for an editor exactly like systemctl:

• https://www.freedesktop.org/software/systemd/man/latest/systemctl.html#%24SYSTEMD_EDITOR

It is highly recommended to either set the environment variables $EDITOR or $VISUAL for a more consistent Linux Terminal experience across different applications.

For the security implications of setting this variable see the systemctl edit security discussion.

Default Pager

# Default pager to open preview tabs in (except for `Journal`). Default = `auto`
# Defaults to the first pager defined in one of the environment variables:
# - `SYSTEMD_PAGER`, `PAGER`
# and then falls back to the first available pager:
# - `less`, `more`.
# 
# Note: Input is always provided via STDIN to the pager!
default_pager: "auto"

The auto logic, searches for and editor exactly like systemctl WITH SYSTEMD_PAGERSECURE=0:

• https://www.freedesktop.org/software/systemd/man/latest/systemctl.html#%24SYSTEMD_PAGER

For the security implications of setting this variable see the pagers discussion.

Journal Pager

# Default pager to open preview for `Journal` tab. Default = `auto`
# Defaults to the first pager defined in one of the environment variables:
# - `SYSTEMD_PAGER`, `PAGER`
# and then falls back to the first available pager:
# - `less`, `more`.
# 
# Note: Input is always provided via STDIN to the pager!
journal_pager: "auto"

auto behaves exactly like Default Pager. Though, it is more common to set this value to a different pager like lnav.

Journal Pager Arguments

# Default arguments for `journalctl` to generate the
# output of the `Journal` preview window.
journalctl_args: 
  - "--catalog"

These values can be adjusted according to personal preference.

Theme

# The theme of the application.
theme: "textual-dark"

isd comes with a few default themes. You can temporarily view the themes via the Change theme command. But to persist the changes you must update the configuration file.

Generic Keybindings

# Configurable keybindings for common actions.
# The actions (keys) are predefined and the configured keybindings
# are given as values.
# 
# Note about keybindings:
# Multiple keys can be defined by separating them with a comma `,`.
# Please note that depending on the terminal, terminal multiplexer, and
# operating system supported keys will vary and may require trial and error.
# See: <https://posting.sh/guide/keymap/#key-format>
generic_keybindings:
  # Next preview tab
  next_preview_tab: "l,right"
  # Previous preview tab
  previous_preview_tab: "h,left"
  # Clear search input.
  clear_input: "ctrl+backspace"
  # Copy highlighted unit path to the clipboard
  copy_unit_path: "ctrl+y"
  # Open in pager
  open_preview_in_pager: "enter"
  # Open in editor
  open_preview_in_editor: "alt+enter"
  # Toggle mode
  toggle_mode: "ctrl+m"
  # Open `config.yaml` file with `editor`.
  # Creates `config.yaml` if it doesn't exist.
  open_config: "alt+o"

Generic keybindings are enabled globally and are not limited to a specific widget. For example, "ctrl+backspace" will clear the search input and focus the search input widget, even if the selection or preview window is currently focused.

If a focused widget already defines the same keybinding, the generic keybinding will have a lower priority. For example, right would switch to the next preview window when the selection window is focused but it would move the cursor to the right if the preview log output is focused.

For the key format, see: https://posting.sh/guide/keymap/#key-format

Selection Keybindings

# Configurable keybindings for the selection window.
selection_keybindings:
  # Down
  down: "down,j"
  # Up
  up: "up,k"
  # Toggle selection.
  toggle_selection: "space"

Keybindings specific to the selection widget.

Preview Keybindings

# Configurable keybindings for preview log windows.
preview_keybindings:
  # Scroll Down
  scroll_down: "down,j"
  # Scroll Up
  scroll_up: "up,k"
  # Scroll Right
  scroll_right: "right,l"
  # Scroll Left
  scroll_left: "left,h"

Keybindings specific for the preview log window. Note that the preview tab header is different to the preview log window.

systemctl Commands

# List of configurable systemctl subcommands.
# The exact subcommand (including arguments) can be defined
# by settings `command`. The keybinding(s) that triggers this
# systemctl subcommand is configured via the `keybinding` key.
# The description is used to describe the subcommand
# and used in the applications command palette to find
# the action.
# 
# Note about keybindings:
# Multiple keys can be defined by separating them with a comma `,`.
# Please note that depending on the terminal, terminal multiplexer, and
# operating system supported keys will vary and may require trial and error.
# See: <https://posting.sh/guide/keymap/#key-format>
systemctl_commands: 
  - keybinding: "ctrl+e"
    command: "edit"
    description: "systemctl edit"
  - keybinding: "alt+e"
    command: "edit --runtime"
    description: "systemctl edit --runtime"
  - keybinding: "ctrl+o"
    command: "stop"
    description: "systemctl stop"
  - keybinding: "ctrl+a"
    command: "start"
    description: "systemctl start"
  - keybinding: "ctrl+l"
    command: "reload"
    description: "systemctl reload"
  - keybinding: "ctrl+n"
    command: "enable"
    description: "systemctl enable"
  - keybinding: "ctrl+r"
    command: "restart"
    description: "systemctl restart"
  - keybinding: "ctrl+k"
    command: "mask"
    description: "systemctl mask"
  - keybinding: "ctrl+u"
    command: "unmask"
    description: "systemctl unmask"

This allows you to configure the systemctl commands and keybindings. It is important to note that the command key may contain spaces (like edit --runtime) but does not include the prefix systemctl, since this will always be inserted. The full command name (for example systemctl start) is used for the description which will be shown in the command palette.

For the security implications of setting these variables see the shell injection section.

Pager Arguments

# Arguments passed to the configured `default_pager`.
# Should NOT be required most of the time.
# As for most pagers, the correct arguments/environment variables are set by default
# if this value is unset (`null`).
default_pager_args: null

If you have to customize the pager arguments for a common pager, please open an issue!

Journal Pager Arguments

# Arguments passed to the configured `journal_pager`.
# Should NOT be required most of the time.
# As for most pagers, the correct arguments/environment variables are set by default
# if this value is unset (`null`).
journal_pager_args: null

If you have to customize the pager arguments for a common pager, please open an issue!

Maximum Preview Lines

# How many lines to show in the preview windows.
# Setting this value too large, especially with long journal entries
# will considerably slow down the application.
# Usually the default should be left as is.
# 
# Note: The output is not trimmed when a pager or editor is opened!
preview_max_lines: 500

This value can mainly be configured if opening the journal preview window takes too long. Though, it should usually not be required to lower this value.

To view the entire output, open the output in the pager.

---

1. More precisely from $XDG_CONFIG_DIR/isd but for most users, it will default to the path above. ↩

2. Although, the code only applies partial updates to the selected units. So even fairly low values should not cause too many issues. ↩