.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "darkman" "1" "2025-11-05"
.PP
.SH NAME
.PP
darkman - control dark-mode and light-mode transitions
.PP
.SH SYNOPSIS
.PP
\fBdarkman\fR [\fIOPTIONS\fR] \fICOMMAND\fR
.PP
.SH DESCRIPTION
.PP
\fBdarkman\fR 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 interactively: it'\&s designed to
be set up once, and run in the background.\&
.PP
It is also possible to trigger manual transitions and it is also possible to
disable automatic transitions entirely.\&
.PP
.SH COMMANDS
.PP
\fBrun\fR [--ready-fd \fIFD\fR]
.RS 4
Runs the darkman service.\& This command is intended to be executed by a
service manager, init script or alike.\&
.PP
The optional \fIFD\fR is a file descriptor  where darkman where notify when
it is ready to receive connections from clients.\& The protocol used is
compatible with readiness notifications for s6, dinit and systemd.\&
.PP
.RE
\fBset\fR <light|dark>
.RS 4
Sets the current mode.\&
.PP
.RE
\fBget\fR
.RS 4
Prints the current mode.\&
.PP
.RE
\fBtoggle\fR
.RS 4
Toggle the current mode.\&
.PP
.RE
.SH OPTIONS
.PP
\fB--verbose\fR
.RS 4
Print detailed logs.\& Default to \fItrue\fR for the \fBrun\fR command and to
\fIfalse\fR for all other commands.\&
.PP
.RE
.SH INTEGRATIONS
.PP
The open source desktop ecosystem is quite heterogeneous and making different
applications switch between dark/light requires different mechanism.\&
.PP
Darkman seeks to implement the more widely adopted standards, while leaving room
for users to hook in custom scripts for other applications.\&
.PP
.SS Custom executables
.PP
Darkman can run custom executables (which can be simple shell scripts).\&
.PP
Scripts are searched in a directory named \fIdarkman\fR inside paths defined in the
\fIXDG_DATA_DIRS\fR as well as \fIXDG_DATA_HOME\fR.\& Each script receives the current
mode ("dark" or "light") as its first argument ($1).\& This allows a single
script to handle both modes:
.PP
.nf
.RS 4
#!/bin/sh
case "$1" in
dark) THEME=dark-theme ;;
light) THEME=light-theme ;;
esac
gsettings set org\&.example\&.app theme "$THEME"
.fi
.RE
.PP
For backwards compatibility, darkman also searches \fIdark-mode.\&d\fR and
\fIlight-mode.\&d\fR directories (legacy format).\& Scripts in these directories run
without arguments.\& Scripts in the \fIdarkman\fR directory with the same name will
override legacy scripts.\&
.PP
Both of these variables and their fallbacks are defined in the XDG Base
Directory Specification:
.PP
.RS 4
https://specifications.\&freedesktop.\&org/basedir-spec/latest/
.PP
.RE
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.\&
.PP
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.\&
.PP
Typically, the \fIXDG_DATA_*\fR variables mentioned above will resolve to the
following set of directories:
.PP
.PD 0
.IP \(bu 4
~/.\&local/share/
.IP \(bu 4
/usr/local/share/
.IP \(bu 4
/usr/share/
.PD
.PP
Example scripts (and discussion on how to integrate different applications) are
available in the project repository:
.PP
.RS 4
https://gitlab.\&com/WhyNotHugo/darkman
.PP
.RE
Packages may also drop-in their own scripts into any of these locations,
although application developers are encouraged to use the D-Bus API to
determine the current mode and listen for changes (see below for details).\&
.PP
.SS XDG Settings portal
.PP
Darkman implements the XDG desktop portal'\&s 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.\&
.PP
For more details on this protocol, see:
.PP
.RS 4
https://flatpak.\&github.\&io/xdg-desktop-portal/docs/doc-org.\&freedesktop.\&portal.\&Settings.\&html
.PP
.RE
As for \fBxdg-desktop-portal\fR version 1.\&17.\&0, portals MUST be configured with
per-user configuration \fBportals.\&conf(5)\fR.\& To force the usage of darkman for
dark/light mode setting, use something like the following:
.PP
.nf
.RS 4
[preferred]
org\&.freedesktop\&.impl\&.portal\&.Settings=darkman
.fi
.RE
.PP
When using a desktop-specific configuration (e.\&g.\&: \fBswaywm-portals.\&conf\fR),
please keep in mind that the environment variable \fBXDG_CURRENT_DESKTOP\fR must be
set for the \fBxdg-desktop-portal\fR.\&
.PP
The \fBxdg-desktop-portal\fR should start after \fBdarkman\fR has started and is ready.\&
Use \fB--ready-fd\fR for readiness notification.\& This is likely not relevant on
systemd-based setups, where the service manager intermediates in taking the
named bus.\&
.PP
For a more in-depth explanation, see this article:
.PP
.RS 4
https://whynothugo.\&nl/journal/2024/04/09/darkman-portal-configuration/
.PP
.RE
.SS D-Bus API
.PP
For custom integrations, darkman exposes a D-Bus API which allows querying and
controlling the current mode.\& The \fBget\fR, \fBset\fR and \fBtoggle\fR commands all use
this API.\& Usage of 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).\&
.PP
.SS Third party integrations
.PP
For Emacs users, a third party package exists to integrate darkman with Emacs:
.PP
.RS 4
https://github.\&com/grtcdr/darkman.\&el
.PP
.RE
There also exists a plugin for neovim users:
.PP
.RS 4
https://github.\&com/4e554c4c/darkman.\&nvim
.PP
.RE
.SH LOCATION
.PP
The current location may be specified in the configuration file.\& The location is
used to calculate what time sundown and sunrise happen.\&
.PP
It is also possible for darkman to automatically determine the system'\&s location
using \fBgeoclue\fR.\& Geoclue'\&s reliability varies depending on distribution and
desktop environment, as an agent often needs to be configured for it to work
properly.\&
.PP
If no location is known, automatic transitions are disabled.\&
.PP
.SH CONFIGURATION
.PP
A configuration file and all settings are optional.\& Configuration is read from
\fB~/.\&config/darkman/config.\&yaml\fR (or other paths defined in the XDG basedir
spec), and has the following format:
.PP
.nf
.RS 4
lat: 52\&.3
lng: 4\&.8
dbusserver: true
.fi
.RE
.PP
The following settings are available:
.PP
.PD 0
.IP \(bu 4
\fBlat\fR, \fBlng\fR: 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/.\&
.PD
.PP
.PD 0
.IP \(bu 4
\fBusegeoclue\fR (true/\fBfalse\fR): 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.\& Setting this to
false without explicitly setting lat and lng disables automatic transitions
entirely.\&
.PD
.PP
.PD 0
.IP \(bu 4
\fBdbusserver\fR (\fBtrue\fR/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.\&
.PD
.PP
.PD 0
.IP \(bu 4
\fBportal\fR (\fBtrue\fR/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.\&
.PD
.PP
.PD 0
.IP \(bu 4
\fBsocketpath\fR: Filesystem path for the query and control socket.\&
The default value is \fB${XDG_RUNTIME_DIR}/darkman/control.\&sock\fR.\&
.PD
.PP
.SH ENVIRONMENT
.PP
The following environment variables are also read and will override the
configuration file:
.PP
\fIDARKMAN_LAT\fR
.RS 4
Overrides the latitude for the current location.\&
.PP
.RE
\fIDARKMAN_LNG\fR
.RS 4
Overrides the longitude for the current location.\&
.PP
.RE
\fIDARKMAN_DBUSSERVER\fR
.RS 4
Overrides whether to expose the current mode via D-Bus.\&
.PP
.RE
\fIXDG_CURRENT_DESKTOP\fR
.RS 4
Darkman does not use this variable; it should be defined for the
\fBxdg-desktop-portal\fR instead.\&
.PP
.RE
.SH PRIVACY
.PP
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 information related the
current location.\&
.PP
When a web browser applies this transition at the same time, open websites can
record this information too.\&
.PP
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.\&
.PP
The author of this tool uses a manually configured location with an integer
latitude and longitude to achieve a sensible balance between privacy and
convenience.\&
.PP
.SH DEVELOPMENT
.PP
For issues and general development inquiries, see the project home currently
hosted at GitLab:
.PP
.RS 4
https://gitlab.\&com/WhyNotHugo/darkman
.PP
.RE
.SH DEBUGGING
.PP
To confirm which value is relayed via the \fBxdg-desktop-portal\fR use:
.PP
.nf
.RS 4
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
.fi
.RE
.PP
.SH SEE ALSO
.PP
portals.\&conf(5)
gammastep(1)
sd-ready-fd(1)
.PP
.SH AUTHORS
.PP
Developed by Hugo O.\& Barrera <hugo@whynothugo.\&nl>, with invaluable contributions
from the community.\&
.PP
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:
.PP
.RS 4
https://whynothugo.\&nl/sponsor