Why does a brightness query return a different value from the monitor’s own menu?

A hardwareBrightness query returns BetterDisplay's managed, normalized brightness value. It does not perform a fresh DDC read from the monitor, so it can differ after you change brightness using the monitor's physical buttons.

To request the monitor's actual DDC luminance value and reported maximum, use:

betterdisplaycli get -name="Desk Display" -ddc -vcp=luminance -value -max

Replace Desk Display with your display's name. This requires an enabled, supported DDC controller and a monitor/connection that supports reading that feature. A failed read does not prove writes are impossible: some displays accept brightness commands but cannot return a usable value.

For ongoing synchronization, open the display's Device Control > DDC Control > Configure Controls… settings. Select brightness and enable Periodically read and update current value from display for brightness, if reads work reliably. Readback is off by default. See DDC Control for frequency and feature configuration.

Also distinguish brightness from hardwareBrightness. The main brightness feature can use combined hardware and software adjustment, so a low normalized value is not necessarily a request for that percentage on the monitor's hardware slider. Direct DDC uses the monitor's raw range. Do not assume every monitor uses 0–100.

A script that writes a value and then reads hardwareBrightness has checked the app's managed value, not independently verified the physical result. Use a successful direct read or the monitor's own information when that distinction matters. See direct DDC examples.