lightum(1)

📦 version 2014-06, in nixos 26.05, nixpkgs unstable

💖 lightum — the `lightum(1)` page, but make it make sense 💖

okay so bestie, you know that lightum page in the User commands section of your manual? this is her, but she's been to therapy and now she actually explains herself. strap in 🎀

✨ NAME ✨

lightum — the MacBook automatic light sensor daemon. yes. she's a daemon. she lives in the background and she handles your vibes (lighting). 👑

✨ SYNOPSIS ✨

lightum [-m value] [-n value] [-M value] [-N value] [-p value] [-i
value] [-I value] [-w {1,2,3}] [-x] [-u] [-l] [-s] [-f] [-v] [-d {1,2,3}]

🌸 DESCRIPTION 🌸

lightum is a daemon — a lil background main character — whose whole job is controlling the keyboard brightness and the monitor backlight on MacBook-based laptops. that's it. that's her purpose. iconic behavior honestly 💅

by default she runs in "auto" mode, which means she reads data from the ambient light sensor (the one living on the iSight camera 👀) and then automatically:

a) lights up or dims the keyboard brightness b) lights up or dims the the video backlight

yes, "the the". we're keeping it. it's canon. 😭

she'll also dim the keyboard brightness and the screen backlight when the computer isn't being used for a configurable amount of seconds — 5 by default. so if you walk away, she notices. not in a creepy way. in a "let me save your battery" way 🫶

if you choose to run her in "manual" mode instead, she will not query the ambient light sensor. nope. she'll just use the brightness and backlight values you set by hand with the function keys. your call, your lighting, your moment ✨

and listen — when you first launch lightum, she creates a config file at ~/.config/lightum/lightum.conf, inside the user's home directory, filled with the default configuration values. very considerate of her. when you launch her with no parameters, she reads the configuration from that config file — but the config values can always be overwritten via the command line. so CLI stays winning. periodt 🔥

⭐ OPTIONS ⭐

the full usage, bestie:

Usage:  lightum [OPTION]...
     -m 4..255 : maximum brightness value in auto mode (default=255)
     -n 0..3   : minimum brightness value in auto mode (default=0)
     -M 7..15  : maximum backlight value in auto mode (default=15)
     -N 1..6   : minimum backlight value in auto mode (default=1)
     -p num    : number of milliseconds between light sensor polls
(default=300)
     -i num    : power off keyboard light on session idle seconds (0 to
disable)
     -I num    : turn down screen backlight on session idle seconds (0
to disable)
     -w num    : 1 manage brightness, 2 manage backlight, 3 both
(default:3)
     -x        : manual mode (will honor the brightness value set with
Fn keys)
     -l        : fully dim the screen backlight when session is idle
     -u        : do not ignore brightness changes happening outside
lightum
     -s        : power off keyboard light when screen saver is active
     -f        : run in foreground (do not daemonize)
     -v        : verbose mode, useful for debugging with -f and -d
     -d num    : debug mode: 1 brightness, 2 backlight, 3 both

and here's the same energy, one bullet per flag, because lists are a love language 💖

-m 4..255 — maximum brightness value in auto mode (default=255). the ceiling, the limit, the "don't blind me" 🕶️
-n 0..3 — minimum brightness value in auto mode (default=0)
-M 7..15 — maximum backlight value in auto mode (default=15)
-N 1..6 — minimum backlight value in auto mode (default=1)
-p num — number of milliseconds between light sensor polls (default=300). how often she checks the vibe. 👀
-i num — power off keyboard light on session idle seconds (0 to disable)
-I num — turn down screen backlight on session idle seconds (0 to disable)
-w num — 1 manage brightness, 2 manage backlight, 3 both (default: 3)
-x — manual mode (will honor the brightness value set with Fn keys). she steps back and lets you drive 🚗
-l — fully dim the screen backlight when session is idle
-u — do not ignore brightness changes happening outside lightum
-s — power off keyboard light when screen saver is active
-f — run in foreground (do not daemonize). she stays right there with you 🫶
-v — verbose mode, useful for debugging with -f and -d. the "tell me everything" mode 🗣️
-d num — debug mode: 1 brightness, 2 backlight, 3 both

🦋 CONFIGURATION FILE 🦋

this is the moment. the config file. ~/.config/lightum/lightum.conf — the blueprint of your lighting destiny 📜

💜 General options 💜

# manualmode
#   0 = automatically adjust keyboard brightness based on light sensor
#   1 = or control keyboard brightness manually using Fn+ F5/F6 keys
manualmode=0

# ignoreuser: only has effect in auto-mode (when manualmode=0)
#   0 = change maxbrightness value dinamically when user presses Fn+ F5/F6
#   1 = ignore brightness changess happening outside lightum and keep the
#       maxbrightness value from the config file (fixes bug in ubuntu 12.04)
ignoreuser=1

# workmode
#   1 = only manage keyboard brightness (ignore screen backlight)
#   2 = only manage screen backlight (ignore keyboard brightness)
#   3 = manage both keyboard brightness and screen backlight
workmode=3

# poll time in milliseconds (used for light sensor and session idle time)
polltime=300

# screensaver
#   1 = turn off keyboard brightness when screensaver is active
#   0 = do not monitor screensaver status
queryscreensaver=0

ngl the dinamically and changess spellings? leaving them EXACTLY as they are. that's her handwriting. artifacts of the era. we respect the lore 💀

also quick note on ignoreuser: it only has effect in auto-mode (when manualmode=0). and 1 is literally the fix for a bug in ubuntu 12.04. so if you're on ubuntu 12.04 in the year of our lord, you're welcome 🎀

🍓 Options to manage keyboard brightness 🍓

# maximum keyboard brightness value (between 4 and 255)
maxbrightness=56

# minimum keyboard brightness value (between 0 and 3)
minbrightness=2

# turn off keyboard brightness if computer unused for X seconds (0 to disable)
idleoff=4

🌈 Options to manage screen backlight 🌈

# maximum screen backlight value (between 4 and 15)
maxbacklight=12

# minimum screen backlight value (between 0 and 3)
minbacklight=2

# turn off screen backlight if computer unused for X seconds (0 to disable)
screenidle=30

# fully dim the backlight when screenidle seconds reached (default 0)
#   1 = when idle, backlight will be set to 1
#   0 = when idle, backlight will be set to minbacklight
fulldim=0

🌟 EXAMPLES 🌟

1) run lightum in auto mode, managing both screen backlight and keyboard brightness automatically — and changing the maximum and minimum values for both options — and changing the idle times to dim them. a whole glow-up, fr fr:

lightum -m 56 -n 2 -i 4 -M 12 -N 2 -I 30

the same command line example, but specified via config file:

manualmode=0
ignoreuser=1
workmode=3
maxbrightness=56
minbrightness=2
polltime=300
idleoff=4
queryscreensaver=0
maxbacklight=12
minbacklight=2
screenidle=30
fulldim=0

same energy, different delivery method. both ate 💅

2) run lightum in manual mode, used only to automatically turn off the keyboard brightness after 10 seconds of idle time:

lightum -x -w 1 -i 10 -n 0

the most niche use case ever and honestly? she serves. 🧚

💀 EXIT STATUS 💀

lightum will return a non zero exit status in case of failure. so if the number isn't zero, something went wrong. that's the vibe check and she failed it 😭

👑 AUTHOR 👑

Written by Pau Oliva Fora. legend. we stan. 🫶

🐛 REPORTING BUGS 🐛

please report bugs here: https://github.com/poliva/lightum/issues

don't suffer in silence bestie. drop the link. the maintainers are listening 🌸

📜 COPYRIGHT 📜

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

"NO WARRANTY" said in full caps because she means it. no cap. redistribute her, remix her, but if she breaks your backlight that's on you 🙈

and that's the page!! made by Pau Oliva Fora, lightum v2.0, dated 2012-05-01 — go forth and let your keyboard glow exactly the right amount ⭐💖✨

📦 where this page comes from

nixos 26.05: lightum-unstable 2014-06-07
nixpkgs unstable: lightum-unstable 2014-06-07
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms