1darkman(1) General Commands Manual darkman(1)
2
6 darkman - daemon for dark-mode and light-mode transitions on Unix-like
7 desktops
8
10 darkman run
11 darkman set [light|dark]
12 darkman get
13 darkman toggle
14
16 darkman runs in the background and turns on dark mode at sundown, and
17 turns it off again at sunrise. darkman is not designed to be used in‐
18 teractively: it's designed to be set up once, and run in the back‐
19 ground.
20 It is, however, possible to trigger manual transitions and even disable
22 automatic transitions entirely.
23
25 run
26 Runs the darkman service. This command is intended to be executed
27 by a service manager, init script or alike.
28 set <light|dark>
30 Sets the current mode.
31 get
33 Prints the current mode.
34 toggle
36 Toggle the current mode.
37
39 The open source desktop ecosystem is quite heterogeneous and switching
40 between dark/light mode on different applications requires different
41 mechanism and techniques.
42 Darkman seeks to implement the more widely supported standards, while
44 leaving room for users to hook in custom scripts for other applica‐
45 tions.
46 Darkman implements the FreeDesktop dark mode standard. Applications us‐
48 ing this API should switch to dark/light mode based on darkman's cur‐
49 rent preference. This standard was originally pushed by the GNOME and
50 Elementary teams, and is currently supported by KDE, Firefox and many
51 other projects. You should expect applications from those environment
52 to support it, amongst others.
53 For additional application support, custom executables (including sim‐
55 ple shell scripts) can be placed in the following two directories:
56 • $XDG_DATA_DIRS/dark-mode.d/: Scripts to run when switching to dark
58 mode.
59 • $XDG_DATA_DIRS/light-mode.d/: Scripts to run when switching to
60 light mode.
61 Scripts need to have an executable bit set, or will not be executed.
64 For additional sample scripts (and discussion on how to integrate dif‐
66 ferent applications) see the project website:
67 https://gitlab.com/WhyNotHugo/darkman
69 For custom integrations, darkman exposes a D-Bus API which allows
71 querying and controlling the current mode. The get, set and toggle com‐
72 mands all use this API. Usage of this API is also the recommended ap‐
73 proach when writing custom tools (e.g.: switching the current mode
74 based on the input from a light sensor).
75 For Emacs users, a third party package exists to integrate darkman with
77 Emacs:
78 https://github.com/grtcdr/darkman.el
80
82 darkman will automatically determine the system's location using geo‐
83 clue. Geoclue's reliability varies depending on distribution and desk‐
84 top environment, and it will often not work without a geoclue agent
85 running.
86 If using geoclue is not an option, the location may be specified ex‐
88 plicitly via a configuration file.
89
91 A configuration file and all settings are optional. Configuration is
92 read from ~/.config/darkman/config.yaml, and has the following format:
93 lat: 52.3
95 lng: 4.8
96 dbusserver: true
97 The following settings are available:
99 • lat, lng: Latitude and longitude respectively. This value will be
101 used at start-up, but will later be superseded by whatever geoclue
102 resolves (if enabled). More than one decimal point is generally not
103 needed, as described in https://xkcd.com/2170/.
104 • usegeoclue (true/false): Whether to use a local geoclue instance to
107 determine the current location. On some distributions/setups, this
108 may require setting up a geoclue agent to function properly. The
109 default for this will change to false in v2.0.
110 • dbusserver (true/false): Whether to expose the current mode via
113 darkman's own D-Bus API. The command line tool uses this API to ap‐
114 ply changes, so it will not work if this setting is disabled.
115 • portal (true/false): Whether to expose the current mode via the XDG
118 settings portal D-Bus API. Many desktop application will read the
119 current mode via the portal and respect what darkman is indicating.
120
123 The following environment variables are also read and will override the
124 configuration file:
125 DARKMAN_LAT
127 Overrides the latitude for the current location.
128 DARKMAN_LNG
130 Overrides the longitude for the current location.
131 DARKMAN_DBUSSERVER
133 Overrides whether to expose the current mode via D-Bus.
134
136 Darkman will trigger a darkmode/lightmode transition at sundown in the
137 current location. When a web browser applies this transition at the
138 same time, open websites can use this information to extrapolate some
139 information about the current location.
140
142 For issues and general development inquiries, see the project home cur‐
143 rently hosted at GitLab:
144 https://gitlab.com/WhyNotHugo/darkman
146
148 gammastep(1)
149
151 Developed by Hugo O. Barrera <hugo@whynothugo.nl>, with invaluable con‐
152 tributions from the community.
153 darkman is an open source project licensed under the ISC licence and
155 developed for anyone to use freely. If you would like to sponsor this
156 project, see:
157 https://whynothugo.nl/sponsor
159 2023-10-22 darkman(1)