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_tui/config.yaml¹. Though you can also simply open the file from within isd by running the Open Config command (Ctrl+G by default). However, you will have to restart isd for the changes to take effect!

Warning

You need to configure the config.yaml file and not the schema.json file. The schema.json file is always automatically generated by isd. This file defines the json-schema for config.yaml file that will only be generated via the Open Config command!

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 'irrelevant' 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"

## Relative height compared to preview height.
# search_results_height_fraction: 1

## Relative height compared to search result height.
# preview_height_fraction: 2

## Uncategorized generic keybindings for
## toggling screens/modals and opening settings.
# generic_keybindings:
#   # Systemctl action
#   toggle_systemctl_modal: "ctrl+o"
#   # Open config in editor
#   open_config: "ctrl+g"

## Configurable keybindings for common actions on the main screen.
## These keybindings must be unique across the entire application.
# main_keybindings:
#   # Next preview tab
#   next_preview_tab: "full_stop"
#   # Previous preview tab
#   previous_preview_tab: "comma"
#   # Clear search input
#   clear_input: "backspace,ctrl+backspace"
#   # Jump to search input
#   jump_to_input: "slash"
#   # Copy highlighted unit path to clipboard
#   copy_unit_path: "ctrl+x"
#   # Open in pager
#   open_preview_in_pager: "enter"
#   # Open in editor
#   open_preview_in_editor: "ctrl+v"
#   # Toggle mode
#   toggle_mode: "ctrl+t"
#   # Increase height of currently focused widget
#   increase_widget_height: "plus"
#   # Decrease height of currently focused widget
#   decrease_widget_height: "minus"

## Keybindings specific to navigation.
## These will be applied to _all_ widgets that
## have any navigational component.
## To avoid confusion, these must be unique across the entire application;
## even if a given widget does not have horizontal navigation.
# navigation_keybindings:
#   # Down
#   down: "down,j"
#   # Up
#   up: "up,k"
#   # Page down
#   page_down: "ctrl+down,ctrl+f,pagedown"
#   # Page up
#   page_up: "ctrl+up,ctrl+b,pageup"
#   # Goto top
#   top: "home"
#   # Goto bottom
#   bottom: "end"
#   # Left
#   left: "left,h"
#   # Right
#   right: "right,l"
#   # Page left
#   page_left: "ctrl+left"
#   # Page right
#   page_right: "ctrl+right"

## List of configurable systemctl subcommand keybindings.
## The exact subcommand (including arguments) can be defined by setting `command`.
## The `modal_keybinding`s provide the shortcut key(s)
## for the modal action window.
## Optionally, `direct_keybinding`s can be configured to
## immediately trigger the systemctl action from the main screen
## without having to open the modal first.
## 
## The description is used to describe the subcommand
## in the `CommandPalette`
# systemctl_commands: 
#   - command: "start"
#     modal_keybinding: "a"
#     direct_keybinding: null
#     description: "Start unit(s)"
#   - command: "stop"
#     modal_keybinding: "o"
#     direct_keybinding: "ctrl+s"
#     description: "Stop unit(s)"
#   - command: "restart"
#     modal_keybinding: "s"
#     direct_keybinding: null
#     description: "Restart unit(s)"
#   - command: "edit"
#     modal_keybinding: "e"
#     direct_keybinding: null
#     description: "Edit highlighted unit via drop-in with configured editor"
#   - command: "edit --full"
#     modal_keybinding: "f"
#     direct_keybinding: null
#     description: "Edit highlighted unit source with configured editor"
#   - command: "edit --runtime"
#     modal_keybinding: "r"
#     direct_keybinding: null
#     description: "Edit highlighted unit only for current runtime"
#   - command: "reload"
#     modal_keybinding: "d"
#     direct_keybinding: null
#     description: "Reload unit(s)"
#   - command: "enable"
#     modal_keybinding: "n"
#     direct_keybinding: null
#     description: "Enable unit(s)"
#   - command: "mask"
#     modal_keybinding: "m"
#     direct_keybinding: null
#     description: "Mask/Disable starting unit(s)"
#   - command: "unmask"
#     modal_keybinding: "u"
#     direct_keybinding: null
#     description: "Undo masking of unit(s)"

## 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 sections will be 😅. Some sections 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
Layout
Keybindings
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 'irrelevant' 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 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.

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

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

Layout¶

isd allows you to customize the layout. Currently, the relative heights between the search results and preview widgets can be adjusted:

# Relative height compared to preview height.
search_results_height_fraction: 1

# Relative height compared to search result height.
preview_height_fraction: 2

By default the preview widget is about twice as tall as the search results widget.

Keybindings¶

With great flexibility comes great responsibility.

This section shows the different keybinding configuration options. For all entries, multiple keys can be defined by separating them with a comma ,.

Warning

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 for more details.

isd is opinionated regarding overlapping keybindings and will usually fail if keybindings are not globally unique. The motivation is simply to ensure that isd does not accidentally stop an important unit, just because the keybinding was overloaded and the focus was accidentally on a different widget.

Reserved Keys¶

Please note that the following keys are reserved and cannot be used for keybindings:

Ctrl+Q
Ctrl+C
Ctrl+Z
Ctrl+P
Esc
Tab
Shift+Tab
Space

Generic Keybindings¶

# Uncategorized generic keybindings for
# toggling screens/modals and opening settings.
generic_keybindings:
  # Systemctl action
  toggle_systemctl_modal: "ctrl+o"
  # Open config in editor
  open_config: "ctrl+g"

See Keybindings for more general information.

Main Keybindings¶

# Configurable keybindings for common actions on the main screen.
# These keybindings must be unique across the entire application.
main_keybindings:
  # Next preview tab
  next_preview_tab: "full_stop"
  # Previous preview tab
  previous_preview_tab: "comma"
  # Clear search input
  clear_input: "backspace,ctrl+backspace"
  # Jump to search input
  jump_to_input: "slash"
  # Copy highlighted unit path to clipboard
  copy_unit_path: "ctrl+x"
  # Open in pager
  open_preview_in_pager: "enter"
  # Open in editor
  open_preview_in_editor: "ctrl+v"
  # Toggle mode
  toggle_mode: "ctrl+t"
  # Increase height of currently focused widget
  increase_widget_height: "plus"
  # Decrease height of currently focused widget
  decrease_widget_height: "minus"

See Keybindings for more general information.

# Keybindings specific to navigation.
# These will be applied to _all_ widgets that
# have any navigational component.
# To avoid confusion, these must be unique across the entire application;
# even if a given widget does not have horizontal navigation.
navigation_keybindings:
  # Down
  down: "down,j"
  # Up
  up: "up,k"
  # Page down
  page_down: "ctrl+down,ctrl+f,pagedown"
  # Page up
  page_up: "ctrl+up,ctrl+b,pageup"
  # Goto top
  top: "home"
  # Goto bottom
  bottom: "end"
  # Left
  left: "left,h"
  # Right
  right: "right,l"
  # Page left
  page_left: "ctrl+left"
  # Page right
  page_right: "ctrl+right"

See Keybindings for more general information.

`systemctl` Keybindings¶

# List of configurable systemctl subcommand keybindings.
# The exact subcommand (including arguments) can be defined by setting `command`.
# The `modal_keybinding`s provide the shortcut key(s)
# for the modal action window.
# Optionally, `direct_keybinding`s can be configured to
# immediately trigger the systemctl action from the main screen
# without having to open the modal first.
# 
# The description is used to describe the subcommand
# in the `CommandPalette`
systemctl_commands: 
  - command: "start"
    modal_keybinding: "a"
    direct_keybinding: null
    description: "Start unit(s)"
  - command: "stop"
    modal_keybinding: "o"
    direct_keybinding: "ctrl+s"
    description: "Stop unit(s)"
  - command: "restart"
    modal_keybinding: "s"
    direct_keybinding: null
    description: "Restart unit(s)"
  - command: "edit"
    modal_keybinding: "e"
    direct_keybinding: null
    description: "Edit highlighted unit via drop-in with configured editor"
  - command: "edit --full"
    modal_keybinding: "f"
    direct_keybinding: null
    description: "Edit highlighted unit source with configured editor"
  - command: "edit --runtime"
    modal_keybinding: "r"
    direct_keybinding: null
    description: "Edit highlighted unit only for current runtime"
  - command: "reload"
    modal_keybinding: "d"
    direct_keybinding: null
    description: "Reload unit(s)"
  - command: "enable"
    modal_keybinding: "n"
    direct_keybinding: null
    description: "Enable unit(s)"
  - command: "mask"
    modal_keybinding: "m"
    direct_keybinding: null
    description: "Mask/Disable starting unit(s)"
  - command: "unmask"
    modal_keybinding: "u"
    direct_keybinding: null
    description: "Undo masking of unit(s)"

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 may not include the prefix systemctl, since this will always be inserted. The description is used to provide additional information about the command in the command palette.

Warning

Make sure to avoid overlaps between the Navigation Keybindings and these modal_keybindings and direct_keybindings!

Generally, it is recommended to use ASCII keys for the modal_keybindings and modifier keys, such as Ctrl or Alt, for the direct_keybindings.

See Keybindings for more general information.

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

# 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!

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

More precisely from $XDG_CONFIG_DIR/isd_tui but for most users, it will default to the path above. ↩
Although, the code only applies partial updates to the selected units. So even fairly low values should not cause too many issues. ↩

Customization¶

Configuration Options¶

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¶

Layout¶

Keybindings¶

Reserved Keys¶

Generic Keybindings¶

Main Keybindings¶

Navigation Keybindings¶

systemctl Keybindings¶

Pager Arguments¶

Journal Pager Arguments¶

Maximum Preview Lines¶

`systemctl` Keybindings¶