darkman - Man Page

daemon for dark-mode and light-mode transitions on Linux desktop

Synopsis

darkman run
darkman set [light|dark]
darkman get
darkman toggle

Description

darkman runs in the background and turns on night mode at sundown, and turns it off again at sunrise. darkman is not designed to be used interactively: it's designed to be set up once, and run in the background.

It is, however, possible trigger manual transitions and even disable automatic transitions entirely.

Commands

run

Runs the darman 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 Linux desktop ecosystem is quite heterogeneous and switching between dark/light mode on different applications requires different mechanism and techniques.

Darkman seeks to implement the more widely supported standards, while leaving room for users to hook in custom scripts for other applications.

Darkman implements the Freedesktop dark mode standard. Applications using this API should switch to dark/light mode based on darkman'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 environment to support it, amongst others.

For additional application support, custom scripts can be places in the following two directories:

  • $XDG_DATA_DIRS/dark-mode.d/: Scripts to run when switching to dark mode.
  • $XDG_DATA_DIRS/light-mode.d/: Scripts to run when switching to light mode.

Scripts need to have an executable bit set, or will not be executed.

For additional sample scripts (and discussion on how to integrate different applications) see the project website:

For custom integrations, darkman exposes a D-Bus API which allows querying and controlling the current mode. The get, set and toggle commands all use this API. Use this API is also the recommended approach when writing custom tools (e.g.: switching the current mode based on the input from a light sensor).

Location

darkman will automatically determine your location using geoclue. Geoclue's reliability varies depending on distribution and desktop environment, and it will often not work without a geoclue agent running.

If using geoclue is not an option, the location may be specified explicitly via a configuration file.

Configuration

A configuration file and all settings are optional. Configuration is read from ~/.config/darkman/config.yaml, 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). You generally don't need more than one decimal point for your location, as described in https://xkcd.com/2170/.
  • dbusserver (true/false): Whether to expose the current mode via darkman's own D-Bus API. The command line tool uses this API to apply 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.
  • 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.

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.

Authors

Developed by Hugo O. Barrera <hugo@whynothugo.nl>, with invaluable contributions 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:

Info

2022-07-21