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 customizeable 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 is 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:

As an AppImage, via
nix, or via
uv.

AppImagenixuv

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 have nix installed, this AppImage will not work! Either use the nix or uv installation instructions!

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 https://github.com/isd-project/isd.

To install isd, add it to your packages list:

# flake.nix
{

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

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

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 --from git+https://github.com/isd-project/isd isd

To install and manage isd via uv, run: uv tool install git+https://github.com/isd-project/isd

For more details regarding the tool management, see the upstream uv tool documentation:

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

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

Command Palette¶

The toolbar at the bottom shows the most important keybindings for the currently focused widget, where the ^ symbol means Ctrl. To open the command palette, press Ctrl+P.

The command palette will show all available commands and their respective keybindings if available.

Commands¶

For example, press Ctrl+O to stop the selected units.

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.

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

To switch to a different tab of the preview widget the arrow keys (Left, Right) or the vim keys (H, L) can be pressed. 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 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:

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!

Next steps¶

Checkout the other sections as well:

If the input is empty, then all units and unit-files are shown. ↩