Watch XKB Keyboard LEDs Without Guessing the State

xkbvleds gives you a live view of keyboard LED state as seen through the X Keyboard Extension (XKB). You will connect it to the right X display, understand which LED sets it watches, and narrow the selection when the default view is too broad. The command observes state; it does not configure Caps Lock, change an XKB layout or alter persistent keyboard settings.

This guide targets xkbvleds 1.0.5, provided here by Debian package x11-xkb-utils version 7.7+8build2. Allow about ten minutes if an X display is already running. You need a shell and access to the X session whose keyboard state you want to inspect.

1. Confirm the installed command

Check which executable your shell will run and record the package version. These are ordinary, read-only checks:

$ command -v xkbvleds
/usr/bin/xkbvleds
$ dpkg-query -W -f='${Package} ${Version}\n' x11-xkb-utils
x11-xkb-utils 7.7+8build2

The installed manual identifies the utility as part of xkbutils 1.0.5. The Debian package version and the upstream utility version are different version labels, so keep both when reporting a problem.

2. Make sure the display is the one you mean

xkbvleds is an X client. It needs a usable DISPLAY and an X server with XKB available. In a normal desktop terminal, the variable is already set:

$ printf 'DISPLAY=%s\n' "${DISPLAY:-<unset>}"
DISPLAY=:0

The value will vary. If you are in an SSH shell, a text console or a different desktop session, do not guess that :0 is correct. Use the display value supplied by the session you intend to inspect. X authority permissions also belong to that session.

Ask the program for its built-in option list only after the display is available:

$ xkbvleds -help

On this installation, running that command with no usable display fails first with Error: Can't open display:. That is a connection problem, not evidence that the option is absent. If you need to test a different display, set it for one command:

$ DISPLAY=:0 xkbvleds -help

Replace :0 with a display you are authorised to access. Do not copy a display value from another user or bypass X access controls. The same connection rule applies to -version.

3. Start with the documented default

Run the command with no selection options:

$ xkbvleds

Keep this process in the terminal while you change a keyboard LED in the same X session. The manual says the default selection is -union +name +automatic +real. In practical terms, it watches named, automatic and real LEDs, combining those sets as a union. The utility reports changes in the fundamental XKB state, including effective compatibility state.

The command is an observer, so there is no configuration to undo. Stop it with Ctrl-C when you have finished. If the command exits immediately, check the terminal's error and the display value before changing filters.

4. Choose LED categories explicitly

The selection switches have a slightly surprising shape: each category accepts either a plus or minus form. A plus form includes that category, while a minus form excludes it. The available categories are:

• +automatic or -automatic;
• +explicit or -explicit;
• +name or -name;
• +real or -real;
• +virtual or -virtual.

For example, this asks for named LEDs while excluding the real and automatic sets:

$ xkbvleds +name -real -automatic

Do not read the switches as keyboard settings. They only alter which LEDs this instance watches. If your target is a physical indicator, start with +real; if it is a logical or named XKB indicator, try +name and compare the result.

5. Decide between union and intersection

-union watches LEDs present in any of the selected sets. -intersection watches only LEDs present in every selected set. Union is the useful first choice when you want a broad view. Intersection is narrower and can produce no visible matches when the selected categories do not overlap.

Use a narrow test when a broad display is distracting:

$ xkbvleds -intersection +name +real

If this shows nothing, that does not prove the keyboard has no LEDs. It may simply mean that no LED belongs to both requested sets. Switch back to -union, or test one category at a time:

$ xkbvleds -union +name -automatic -explicit -virtual

The exact visible state depends on the X server, keyboard definition and current layout. Avoid documenting a particular LED name or output line as universal.

6. Use an explicit LED mask when categories are not enough

-indpy <name> supplies a mask of LEDs to watch. The manual describes the argument as a name, but it does not define a portable list of names in the command's synopsis. Treat the value as host-specific: use a name known from the XKB setup you are debugging, and quote it if it contains shell-significant characters.

$ xkbvleds -indpy 'LED_NAME'

LED_NAME is a placeholder, not a value to paste unchanged. If you do not already have a verified indicator name, use the category filters instead. The -watch <leds> option turns on synchronisation for the supplied LEDs; do not add it merely to make an unknown name work.

7. Diagnose the common failures

"Can't open display" means the client could not connect to the X display named by DISPLAY. Check the variable, the X session, and authorisation. Running as root is not a general fix and can select the wrong authority database.

No useful change appears can mean that the selected set is empty, the LED did not change in the same X session, or the server reports that indicator through a different category. Retry with the documented default, then move to one category or -union before using -intersection.

A guessed -indpy name fails because the mask is not a universal keyboard configuration file. Remove it and establish the host's actual XKB indicator name first. None of these diagnostics changes the keyboard map or writes a configuration file.