Getting Started¶

isd – a better way to work with systemd units

Simplify systemd management with isd! isd is a TUI offering fuzzy search for units, auto-refreshing previews, smart sudo handling, and a fully customizable interface for power-users and newcomers alike.

Short Motivation¶

Note

If you prefer an example terminal recording over text, jump to the next section.

If you ever became frustrated while typing:

systemctl start --user unit-A.service (manually starting a unit ⬆️)
systemctl status --user unit-A.service (seeing that it failed ❌)
journalctl -xe --user -u unit-A.service (checking the logs 🔬)
systemctl edit --user unit-A.service (updating the unit 🧑‍🔬)
systemctl start --user unit-A.service (starting it again ⬆️)
systemctl status --user unit-A.service (checking the logs again 🔬)
And repeat 🔁

This tool is for you!

But isd is not only designed for systemd power-users! isd lowers the bar to interact with systemd units and provides a unified interface that only shows relevant information and commands. If you only ever run systemctl status <unit>, then isd might still be for you, since isd will auto-refresh the output.

If you are interested, read on and take a look at the recorded terminal session.

Installation¶

isd can currently be installed in three different ways:

via uv, or via
nix, or
as an AppImage.

uvnixAppImage

uv is a Python package manager. To install uv have a look at the official uv installation documentation.

After installing uv, you can try isd by running: uvx --python=3.12 isd-tui

To install and manage isd via uv, run: uv tool install --python=3.12 isd-tui

After installing the tool, the program isd and its alias² isd-tui will be available.

isd requires --python to be set >=3.12 and would fail if the default Python version is older. For more details regarding the tool management, see the upstream uv tool documentation:

https://docs.astral.sh/uv/guides/tools/#installing-tools

isd is developed with a reproducible nix environment and build as a nix package. This is my personal preference to install isd but it is a higher barrier compared to the .AppImage. To install nix with sensible default options, use the nix-installer from determinate.systems.

Then, to try out isd, simply run nix run github:isd-project/isd.

To install isd, add it to your packages list:

# flake.nix
{

    # [...]
    inputs.isd.url = "github:isd-project/isd";
    # [...]

    outputs = {self, ...}@inputs: {
      # [...]
      # inside nixosConfigurations.<system>.modules or
      # {
      #     environment.systemPackages = [ inputs.isd.packages.<system>.default ];
      # };
      # homeConfigurations.<name>.modules =
      # {
      #   home.packages = [ inputs.isd.packages.<system>.default ];
      # };
    };
}

An AppImage is a single self-containing executable, similar to a Windows .exe and MacOS .dmg file. This should make it easy to run isd on any Linux distribution and on remote servers where you do not have elevated privileges.

Manual installation:

First, download the .AppImage file from:

https://github.com/isd-project/isd/releases/latest

Then make the file executable as mentioned in the AppImage documentation and run the application.

Managed installation:

Or manage the .AppImage via AppImageLauncher for better desktop integration support (application icon & entry) and in-app update functionality.

Warning

If you are using Ubuntu 24.04, extra installation steps are required. Please see the open issue #10.

Warning

If you have nix installed, this AppImage will not work! Either use the nix or uv installation instructions!

Warning for Windows WSL users

The systemd support of WSL seems to be quite buggy (also for WSL 2). See these GitHub issues for more details

Working with `isd`¶

The following recorded terminal session shows how isd can be used to:

Search through systemd units with fuzzy search,
View the current state of all matched units,
See more detailed status information about multiple units in the preview,
Send systemctl commands to the selected units with auto-refreshing status outputs,
Open the full status output in a dedicated pager without leaving isd,
Open a different pager for the Journal output, and
Customize the theme.

User/System `mode`¶

The top row shows in which mode isd is running. The mode can either be user or system and configures which types of units are shown and searched in the widgets below.

Fuzzy search¶

The top widget is the fuzzy search bar. isd will load all units and unit files that match the input¹ and highlight them according to their current state in the search result widget below. To switch from the current search widget to the next widget either press Tab or Enter.

Selecting multiple units¶

The search result widget can be navigated with the arrow keys (Up, Down) or the vim keys (J, K). Multiple units can be selected with Space. Selected widgets are highlighted on the left side by an additional bar in an accent color, where the currently highlighted unit is always considered selected.

Depending on the currently selected units, the preview widget will show a preview of the selected units for a given output (Status by default).

`systemctl action`¶

The toolbar at the bottom shows the most important keybindings for the currently focused widget, where the ^ symbol means Ctrl. To open the systemctl action modal, press Ctrl+O.

This modal will show a list of possible actions that can be applied to the currently selected/highlighted units. To select the desired action navigate the list with the same keys as for the search result widget and then press Enter to select the unit. Or type any of the colored shortcut keys to directly execute the action.

After running a systemctl command, a notification is shown about the executed command and if necessary, error messages. The selection and preview widget will automatically update to show the new state of the selected units.

Command Palette¶

To open the command palette, press Ctrl+P. The command palette will show all currently available commands and their respective keybindings if available.

Note

The command palette also includes the same actions as the systemctl actions modal. However, the systemctl actions modal provides a cleaner interface and is generally recommended over running these actions via the command palette. Though, you can use whatever you prefer 👍

The command palette also uses fuzzy searching to make it easier to find the command you are interested in.

To view the entire preview output, a pager can be opened while running isd and without closing the application. The pager can be opened by pressing Enter while focusing the search result widget or via the command palette:

Then you can efficiently navigate the text with the pager of your choice. By deeply integrating with pagers isd avoids the need to re-invent the wheel for code navigation and gives you full control over how you would like to navigate the text. Here, for example, showing the output in moar.

Journal Support¶

To switch to a different tab of the preview widget the arrow keys (Left, Right) or the vim keys (H, L) can be pressed while focusing the tab header or globally by triggering the Next/Previous Preview Tab actions.

The next image shows the preview for the Journal output of the selected units:

Similarly to the Status output, the output of the Journal preview window can be opened in a pager. To provide more flexibility, isd allows you to configure a special pager for the Journal output. In this example, lnav is used to view the Journal output.

Customizeability¶

One core feature of isd is it customizability and configurability. You decide which keybindings work best for you and maximize your productivity 🚀. It also comes with a couple of different themes. For example, the dracula theme:

Quitting¶

To quit the application you can either press Ctrl+Q or stop it via the command palette:

Summary¶

I hope that this short overview has helped you to get a feeling for what isd is and if it can be useful for you. If you are still unsure, try it out! It is a lot easier to get feeling for the tool when you try it on your own :)

Support

If you like isd, please give it a on GitHub!

And if you really like it and can afford it, consider buying me a coffee via ko-fi.

Next steps¶

Checkout the other sections as well:

If the input is empty, then all units and unit-files are shown. ↩
The reason why the isd-tui alias exists is due to a naming conflict on PyPI with a different package called isd. Providing the alias isd-tui allows uv users to try it without having to write uvx --from isd-tui isd. ↩