1darkman(1) General Commands Manual darkman(1)
2
6 darkman - daemon for dark-mode and light-mode transitions on Linux
7 desktop
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 Linux desktop ecosystem is quite heterogeneous and switching be‐
40 tween 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
77 darkman will automatically determine the system's location using geo‐
78 clue. Geoclue's reliability varies depending on distribution and desk‐
79 top environment, and it will often not work without a geoclue agent
80 running.
81 If using geoclue is not an option, the location may be specified ex‐
83 plicitly via a configuration file.
84
86 A configuration file and all settings are optional. Configuration is
87 read from ~/.config/darkman/config.yaml, and has the following format:
88 lat: 52.3
90 lng: 4.8
91 dbusserver: true
92 The following settings are available:
94 • lat, lng: Latitude and longitude respectively. This value will be
96 used at start-up, but will later be superseded by whatever geoclue
97 resolves (if enabled). More than one decimal point is generally not
98 needed, as described in https://xkcd.com/2170/.
99 • usegeoclue (true/false): Whether to use a local geoclue instance to
102 determine the current location. On some distributions/setups, this
103 may require setting up a geoclue agent to function properly. The
104 default for this will change to false in v2.0.
105 • dbusserver (true/false): Whether to expose the current mode via
108 darkman's own D-Bus API. The command line tool uses this API to ap‐
109 ply changes, so it will not work if this setting is disabled.
110 • portal (true/false): Whether to expose the current mode via the XDG
113 settings portal D-Bus API. Many desktop application will read the
114 current mode via the portal and respect what darkman is indicating.
115
118 The following environment variables are also read and will override the
119 configuration file:
120 DARKMAN_LAT
122 Overrides the latitude for the current location.
123 DARKMAN_LNG
125 Overrides the longitude for the current location.
126 DARKMAN_DBUSSERVER
128 Overrides whether to expose the current mode via D-Bus.
129
131 Darkman will trigger a darkmode/lightmode transition at sundown in the
132 current location. When a web browser applies this transition at the
133 same time, open websites can use this information to extrapolate some
134 information about the current location.
135
137 For issues and general development inquiries, see the project home cur‐
138 rently hosted at GitLab:
139 https://gitlab.com/WhyNotHugo/darkman
141
143 Developed by Hugo O. Barrera <hugo@whynothugo.nl>, with invaluable con‐
144 tributions from the community.
145 darkman is an open source project licensed under the ISC licence and
147 developed for anyone to use freely. If you would like to sponsor this
148 project, see:
149 https://liberapay.com/WhyNotHugo/
151 2022-10-31 darkman(1)