Skip to content
ShellCode33 edited this page Nov 16, 2026 · 3 revisions

Command-line reference

Brightness and mode

backlightctl                 # Group brightness and current mode
backlightctl -b 60%          # Set all enabled devices to a logical 60%
backlightctl -b +5%          # Increase each target by 5 percentage points
backlightctl -b -5%          # Decrease each target by 5 percentage points
backlightctl --auto          # Resume automatic control immediately

-b is short for --brightness. Values require a % suffix. Absolute values range from 0 to 100; relative magnitudes range from 0 to 100. Relative increases stop at 100, and decreases stop at 1 to avoid accidentally blacking out the screen. An explicit 0% remains allowed, but calibration with a positive hardware minimum means logical zero will not be dark. Use power commands to turn a device off.

A brightness command selects manual mode and resets its override timer. The configured default is twelve hours, including time suspended; "forever" disables automatic expiry. --auto returns to the schedule regardless of that timer. There is no per-device write selector in the CLI; device-specific behavior is configured in TOML. --auto and --brightness cannot be combined.

Power

backlightctl --turn-off
backlightctl --turn-on

These affect enabled devices, independently of stored brightness targets. Sysfs uses bl_power; external monitors use DDC/CI power commands. They do not invoke compositor DPMS, and driver support varies. Power commands do not establish a persistent power policy or change auto/manual mode. In auto mode, scheduled brightness writes continue; whether those wake a powered-off external monitor is hardware-dependent.

Keep a way to send --turn-on when testing, such as SSH or another visible screen. --turn-on and --turn-off cannot be combined.

Status and device details

backlightctl --json
backlightctl --devices
backlightctl --devices --json
backlightctl --refresh --devices --json

Ordinary JSON has this shape:

{"brightness_percent":60,"mode":"manual"}

The percentage is the integer average of retained logical targets across enabled devices, using cached values. Devices without a retained target use their inverse-mapped hardware value. It is not a fresh hardware measurement. An empty managed set reports 0. See Brightness-and-calibration for the meaning of requested, hardware, readback, and actual values.

--devices lists discovered devices, including disabled ones, with configuration IDs and detailed readings. With --json, it prints an array. It cannot be combined with brightness, auto, power, or hotplug-notification commands; --refresh is allowed.

Discovery and integration flags

--refresh (-r) performs full discovery and waits for completion. It can precede a relative brightness command when an external control change should be reread first. Other clients can keep adjusting known devices while background enumeration runs. Brightness probes and writes still serialize on the controller, so an individual hardware operation can cause a short delay. Startup and error recovery remain synchronous. Discovery is also automatic; regular status does not itself discover devices.

--notify-hotplug is for the installed udev rule. It queues a debounced notification, returns without waiting for discovery, and prints no status. Do not use it as a replacement for a synchronous --refresh in scripts needing the result.

--unix-socket-path PATH (-u) selects another daemon socket. The default is /run/backlightd.sock. --help and --version display client information.

Daemon arguments

backlightd --help
backlightd --check-config
backlightd --config ./my-config.toml --check-config

The daemon also accepts --unix-socket-path PATH. Run validation freely; starting a second daemon for diagnostics is unnecessary and can change brightness if a different socket allows it to run. Errors are written to stderr and cause nonzero exit status. A command may partially succeed across monitors and still report an error when a device remains unavailable.

Clone this wiki locally