FreeBSD Manual Pages
darkman(1) General Commands Manual darkman(1) NAME darkman - daemon for dark-mode and light-mode transitions on Unix-like desktops SYNOPSIS darkman run darkman set [light|dark] darkman get darkman toggle DESCRIPTION darkman runs in the background and turns on dark mode at sundown, and turns it off again at sunrise. darkman is not designed to be used in- teractively: it's designed to be set up once, and run in the back- ground. It is also possible to trigger manual transitions and it is also possi- ble to disable automatic transitions entirely. COMMANDS run Runs the darkman service. This command is intended to be executed by a service manager, init script or alike. set <light|dark> Sets the current mode. get Prints the current mode. toggle Toggle the current mode. INTEGRATIONS The open source desktop ecosystem is quite heterogeneous and making different applications switch between dark/light different mechanism and techniques. Darkman seeks to implement the more widely adopted standards, while leaving room for users to hook in custom scripts for other applica- tions. Custom executables For any sort of custom integration, executables (including simple shell scripts) can be placed in the following two directories: • $XDG_DATA_DIRS/dark-mode.d/: Executed when switching to dark mode. • $XDG_DATA_DIRS/light-mode.d/: Executed when switching to light mode. These scripts or executables can perform any actions required, like telling re-writing configuration files for a PDF reader, or controlling a notification daemon to switch to another theme. Scripts need to have an executable bit set, or will not be executed. The variable `$XDG_DATA_DIRS` is defined in the xdg basedir specifica- tion, and usually matches the following, amongst others: • ~/.local/share/ • /usr/local/share/ • /usr/local/share/ Example scripts (and discussion on how to integrate different applica- tions) are available in the project repository: https://gitlab.com/WhyNotHugo/darkman Packages may also drop-in their own scripts into any of these loca- tions, although application developers are encouraged to use the D-Bus API to determine the current mode and listen for changes (see below for details). XDG Settings portal Darkman implements the XDG desktop portal's dark mode standard. Appli- cations using this API should switch to dark/light mode based on dark- man's current preference. This standard 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 en- vironment to support it, amongst others. For more details on this protocol, see: https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesk- top.portal.Settings.html As for xdg-desktop-portal 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-por- tals.conf), please keep in mind that the environment variable XDG_CUR- RENT_DESKTOP must be set for the xdg-desktop-portal. The xdg-desktop-portal 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 intermedi- ates in taking the named bus. For a more in-depth explanation, see this article: https://whynothugo.nl/journal/2024/04/09/darkman-portal-configura- tion/ D-Bus API For custom integrations, darkman exposes a D-Bus API which allows querying and controlling the current mode. The get, set and toggle com- mands all use this API. Usage of this API is also the recommended ap- proach when writing custom tools (e.g.: switching the current mode based on the input from a light sensor). Third party integrations 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 LOCATION The current location may be specified in the configuration file. The location is used to calculate what time sundown and sunrise happen. It is also possible for darkman to automatically determine the system's location using geoclue. Geoclue's reliability varies depending on dis- tribution and desktop environment, as an agent often needs to be con- figured for it to work properly. If no location is known, automatic transitions are disabled. CONFIGURATION A configuration file and all settings are optional. Configuration is read from ~/.config/darkman/config.yaml (or other paths defined in the XDG basedir spec), and has the following format: lat: 52.3 lng: 4.8 dbusserver: true The following settings are available: • lat, lng: Latitude and longitude respectively. This value will be used at start-up, but will later be superseded by whatever geoclue resolves (if enabled). More than one decimal point is generally not needed, as described in https://xkcd.com/2170/. • usegeoclue (true/false): Whether to use a local geoclue instance to determine the current location. On some distributions/setups, this may require setting up a geoclue agent to function properly. Set- ting this to false without explicitly setting lat and lng disables automatic transitions entirely. • dbusserver (true/false): Whether to expose the current mode via darkman's own D-Bus API. The command line tool uses this API to ap- ply changes, so it will not work if this setting is disabled. • portal (true/false): Whether to expose the current mode via the XDG settings portal D-Bus API. Many desktop application will read the current mode via the portal and respect what darkman is indicating. ENVIRONMENT The following environment variables are also read and will override the configuration file: DARKMAN_LAT Overrides the latitude for the current location. DARKMAN_LNG Overrides the longitude for the current location. DARKMAN_DBUSSERVER Overrides whether to expose the current mode via D-Bus. XDG_CURRENT_DESKTOP Darkman does not use this variable; it should be defined for the xdg-desktop-portal instead. PRIVACY Darkman will trigger a darkmode/lightmode transition at sundown in the current location. Any application that is running locally can record or transmit the time of these transitions and attempt to extrapolate in- formation related the current location. When a web browser applies this transition at the same time, open web- sites can record this information too. A potential stalker or tracker can use the above information to infer that you are likely in a region of the world where sunset happened at a specific time. This region is usually a wide area spanning tens of thousands of kilometers, but can be smaller for certain geographical locations. The author of this tool uses a manually configured location with an in- teger latitude and longitude to achieve a sensible balance between pri- vacy and convenience. DEVELOPMENT For issues and general development inquiries, see the project home cur- rently hosted at GitLab: https://gitlab.com/WhyNotHugo/darkman DEBUGGING To confirm which value is relayed via the xdg-desktop-portal use: gdbus call --session \ --dest org.freedesktop.portal.Desktop \ --object-path /org/freedesktop/portal/desktop \ --method org.freedesktop.portal.Settings.ReadOne \ org.freedesktop.appearance color-scheme SEE ALSO portals.conf(5) gammastep(1) AUTHORS Developed by Hugo O. Barrera <hugo@whynothugo.nl>, with invaluable con- tributions from the community. darkman is an open source project licensed under the ISC licence and developed for anyone to use freely. If you would like to sponsor this project, see: https://whynothugo.nl/sponsor 2025-04-14 darkman(1)
NAME | SYNOPSIS | DESCRIPTION | COMMANDS | INTEGRATIONS | LOCATION | CONFIGURATION | ENVIRONMENT | PRIVACY | DEVELOPMENT | DEBUGGING | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=darkman&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>