darkman - Man Page

darkman can run custom executables (which can be simple shell scripts).

Scripts are searched in a directory named darkman inside paths defined in the XDG_DATA_DIRS as well as XDG_DATA_HOME. Each script receives the current mode (“dark or “light””) as its first argument ($1). This allows a single script to handle both modes:

#!/bin/sh
case "$1" in
dark) THEME=dark-theme ;;
light) THEME=light-theme ;;
esac
gsettings set org.example.app theme "$THEME"

For backwards compatibility, darkman also searches dark-mode.d and light-mode.d directories (legacy format). Scripts in these directories run without arguments. Scripts in the darkman directory with the same name will override legacy scripts.

Both of these variables and their fallbacks are defined in the XDG Base Directory Specification: https://specifications.freedesktop.org/basedir-spec/latest/

These scripts or executables can perform any actions required like re-write configuration files for a PDF reader, control a notification daemon to switch to another theme, or toggle a DE-specific setting.

Files must have the executable bit set in order to be considered an executable. Scripts must have the proper shebang for the OS to properly execute them.

Typically, the XDG_DATA_* variables mentioned above will resolve to the following set of directories:

• ~/.local/share/

• /usr/local/share/

• /usr/share/

Example scripts (and discussion on how to integrate different applications) are available in the project repository: https://gitlab.com/WhyNotHugo/darkman

Packages may also drop-in their own scripts into any of these locations, although application developers are encouraged to use the socket API to determine the current mode and listen for changes (see below for details).

darkman implements the XDG desktop portal's dark mode interface. Applications using this API should switch to dark/light mode based on darkman's current preference. This interface was originally pushed by the GNOME and Elementary teams, and is currently supported by KDE, Firefox and many other projects. You should expect applications from those environments to support it, amongst others.

For more details on this protocol, see: https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Settings.html

As of xdg-desktop-portal(1) version 1.17.0, portals MUST be configured with per-user configuration portals.conf(5). To force the usage of darkman for dark/light mode setting, use something like the following:

[preferred]
org.freedesktop.impl.portal.Settings=darkman

When using a desktop-specific configuration (e.g.: swaywm-portals.conf), please keep in mind that the environment variable XDG_CURRENT_DESKTOP must be set for the xdg-desktop-portal(1).

The xdg-desktop-portal(1) should start after darkman has started and is ready. Use --ready-fd for readiness notification. This is likely not relevant on systemd-based setups, where the service manager intermediates in taking the named bus.

For a more in-depth explanation, see this article: https://whynothugo.nl/journal/2024/04/09/darkman-portal-configuration/

darkman listens on a Unix socket for query and control commands. The socket exposes a simple text-based API where commands are followed by a newline, and darkman writes a response also followed by a newline.

The get, set and toggle commands use this API. It is also the recommended approach when writing custom tools (e.g.: switching the current mode based on the input from a light sensor).

The following commands are available:

get

Print the current mode.

set mode

Set the current mode. mode must be one of light or dark.

toggle

Switch to the opposite mode. The new mode is printed as a response.

watch

Print mode changes as they occur. The current mode is printed immediately, followed by each subsequent change.

To interact with the socket manually:

socat UNIX-CONNECT:${XDG_RUNTIME_DIR}/darkman/control.sock STDIO

A libdarkman Go package is available to query this interface from other client applications. See its documentation for details: https://godocs.io/gitlab.com/WhyNotHugo/darkman/libdarkman

For Emacs users, a third party package exists to integrate darkman with Emacs: https://github.com/grtcdr/darkman.el

There also exists a plugin for neovim users: https://github.com/4e554c4c/darkman.nvim