kitten-desktop-ui(1)

Name
kitten-desktop-ui - kitten Documentation

Overview

Added in version 0.43.0.

Power users of terminals on Linux also often like to use bare bones window managers instead of full fledged desktop environments. This kitten helps provide parts of the desktop environment that are missing from such setups, and does so using keyboard friendly, terminal first, UI components. Some of its features are:

•   Replace the typical File Open/Save dialogs used in GUI programs with the fast and keyboard centric choose-files <> kitten running in a semi-transparent kitty overlay.

•   Allow simple command line based management of the desktop light/dark modes.

How to install

Note: This kitten relies on the panel kitten <> under the hood to supply UI components. Check the documentation <#panel-compat> of that kitten to see if your window manager works with it.

First, run:

    kitten desktop-ui enable-portal

Then, set the following two environment variables, system wide, that means in /etc/environment or the equivalent for your distribution:

    QT_QPA_PLATFORMTHEME=xdgdesktopportal
    GTK_USE_PORTAL=1

Finally, reboot. Now, when you open a file dialog in most GUI applications, it should open the choose-files kitten <> instead of a normal file open dialog. You can change the current light/dark mode of your desktop by running:

    kitten desktop-ui set-color-scheme dark
    kitten desktop-ui set-color-scheme light

Check the current value using:

    dbus-send --session --print-reply --dest=org.freedesktop.portal.Desktop /org/freedesktop/portal/desktop org.freedesktop.portal.Settings.Read string:org.freedesktop.appearance string:color-scheme

How it works

Modern Linux desktops have so called portals <https://flatpak.github.io/xdg-desktop-portal/docs/index.html> that were invented for sandboxed applications and provide various facilities to such applications over DBUS, including file open dialogs, common desktop settings, etc. This kitten works by implementing a backend for some of these services.

Normal GUI applications can then be told to make use of these services, thereby allowing us to replace parts of the desktop experience as needed.

There are multiple competing implementations of the backends. Each desktop environment like KDE or GNOME has it's own backend and many window managers provide implementations for some backends as well. Service discovery and configuring which backend to use happens via the xdg-desktop-portal program, usually found at /usr/lib/xdg-desktop-portal.

It can be configured by files in ~/.local/share/xdg-desktop-portal. See man portals.conf <https://man.archlinux.org/man/portals.conf.5>. The kitten desktop-ui enable-portal command takes care of the setup for you automatically. If you want to customize exactly which services to use this kitten for, run the command and then edit the conf file that the command says it has patched.

Troubleshooting

First, ensure that DBUS is able to auto-start the kitten when it is needed. If the kitten is not already running, try the following command:

    dbus-send --session --print-reply --dest=org.freedesktop.impl.portal.desktop.kitty \
        /net/kovidgoyal/kitty/portal org.freedesktop.DBus.Properties.GetAll \
        string:net.kovidgoyal.kitty.settings

If DBUS is able to start the kitten or if it is already running it will print out the version property, otherwise it will fail with an error. If it fails, check the file ~/.local/share/dbus-1/services/org.freedesktop.impl.portal.desktop.kitty.service that should have been created by the enable-portal command. It's Exec key must point to the full path to the kitten executable.

Next, check that the XDG portal system is actually using this kitten for its settings backend. Run:

    dbus-send --session --print-reply --dest=org.freedesktop.portal.Desktop \
        /org/freedesktop/portal/desktop org.freedesktop.portal.Settings.Read \
        string:net.kovidgoyal.kitty string:status

If this returns a reply then the kitten is being used, as expected. If it returns a not found error, then some other backend is being used for settings.

Read the portals.conf man page and run:

    /usr/lib/xdg-desktop-portal -r v

this will output a lot of debug information, which should tell you which backend is chosen for which service. Read the debug output carefully to determine why the kitten is not being selected.

If some GUI applications are not using the choose-files kitten for their file select dialogs, then make sure the environment variables mentioned above are set, you can also try running the GUI application with them set explicitly, as:

    QT_QPA_PLATFORMTHEME=xdgdesktopportal GTK_USE_PORTAL=1 my-gui-app

Note that not all applications use portals, so if some particular application is failing to use the portal but others work, report the issue to that applications' developers.

Configuration

You can configure various aspects of the kitten's operation by creating a desktop-ui-portal.conf in your kitty config folder <#confloc>. See below for the supported configuration directives.

Appearance

color_scheme

        color_scheme no-preference

    The color scheme for your system. This sets the initial value of the color scheme. It can be changed subsequently by using kitten desktop-ui color-scheme.

accent_color

        accent_color cyan

    The RGB accent color for your system, can be specified as a color name or in hex a decimal format.

contrast

        contrast normal

    The preferred contrast level.

file_chooser_size

    The size in lines and columns of the file chooser popup window. By default it is full screen. For example: file_chooser_size 25 80 will cause the popup to be of size 25 lines and 80 columns. Note that if you use this option, depending on the compositor you are running, the popup window may not be properly modal.

file_chooser_kitty_conf

    Path to config file to use for kitty when drawing the file chooser window. Can be specified multiple times. By default, the normal kitty.conf is used. Relative paths are resolved with respect to the kitty config directory.

file_chooser_kitty_override

    Override individual kitty configuration options, for the file chooser window. Can be specified multiple times. Syntax: name=value. For example: font_size=20.

Author
Kovid Goyal

Copyright
2026, Kovid Goyal