bdui — BetterDisplay TUI

bdui is a fast, keyboard-driven terminal UI (TUI) for controlling your displays on macOS. It is a thin wrapper over betterdisplaycli — it never reimplements any display logic, it only builds and reads the CLI commands for you and presents them through an fzf menu.

Every feature betterdisplaycli exposes is reachable from a single menu tree: brightness, contrast, color temperature, gamma, resolution, refresh rate, HDR/XDR, audio (DDC), virtual screens, display groups, and much more.

Displays…                    → pick a display → per-display category menus
System settings…             → system-wide, app UI, global display management
Virtual screens & groups…    → create/manage virtual screens and display groups

Highlights

• fzf-driven — fuzzy-search every menu, every feature.
• Live-apply sliders — numeric features (brightness, contrast, temperature, gamma, volume, zoom, alpha, …) use an arrow-key slider that applies on every step. ←/→ adjust, ↑/↓ take bigger steps, Enter confirms, q/Esc cancels and restores the original value.
• Current value everywhere — every menu label shows the feature's current value (or ? when the display doesn't report it).
• Pickers pull real options — resolution, refresh rate, XDR preset, input source, color profile, and other pickers read their options straight from the matching *List feature.
• Safe targeting — displays are always targeted by -tagID, never by name.
• Pro-aware — BetterDisplay Pro features are still shown; bdui attempts them and reports back if your license doesn't cover them. Built-in / XDR-only rows are hidden on displays where they don't apply.

Requirements

• macOS with BetterDisplay installed. betterdisplaycli ships with the BetterDisplay app and must be on your PATH.
• fzf — brew install fzf
• bash ≥ 4 — macOS ships bash 3.2, so install a modern bash: brew install bash (bdui uses #!/usr/bin/env bash and requires 4+).

Some features (Night Shift, True Tone, Dark Mode, gamma/temperature color adjustments, XDR brightness upscaling, PIP, streaming, EDID overrides, and more) require a BetterDisplay Pro license. bdui lists these features regardless; if the operation isn't available it will surface a (failed / not supported) note and continue.

Install

Homebrew (tap)

brew tap terzigolu/betterdisplay-tui https://github.com/terzigolu/betterdisplay-tui
brew install bdui

…or in one line:

brew install terzigolu/betterdisplay-tui/bdui

The formula installs bin/bdui plus the lib/*.sh modules and pulls in fzf and bash as dependencies. BetterDisplay itself must be installed separately (it provides betterdisplaycli).

Pre-release note: until a tagged release tarball is published, the formula's url/sha256 are placeholders, so the stable tap install above will fail checksum verification. In the meantime install from git head:

brew install --HEAD terzigolu/betterdisplay-tui/bdui

or use the manual installer below.

Manual installer

curl -fsSL https://raw.githubusercontent.com/terzigolu/betterdisplay-tui/main/install.sh | bash

This copies bin/bdui and lib/ into ~/.local (override with PREFIX=/usr/local). It checks for fzf, bash ≥ 4, and betterdisplaycli, then prints a PATH hint if needed.

Run from a clone (development)

git clone https://github.com/terzigolu/betterdisplay-tui.git
cd betterdisplay-tui
./bin/bdui

bin/bdui resolves its lib/ directory relative to itself, so no install is required to try it out.

Usage

bdui            # launch the interactive menu
bdui --help     # usage
bdui --version  # version string

Navigate with the arrow keys or type to fuzzy-filter; Enter selects, Esc goes back. Numeric features open the live slider; toggles flip on/off; pickers show a searchable option list; info screens open in a pager.

You can point bdui at a different CLI binary for testing with BDUI_CLI=/path/to/betterdisplaycli.

Feature overview

Per display

Category	Examples
Brightness	brightness, combined/hardware/software brightness, brightness in nits, brightness upscaling (Pro, built-in)
Color & Image	contrast, gain, gamma (+ per-channel R/G/B), temperature, saturation, hue, quantization, invert, reset
Black Level & Gain	per-channel hardware black level and gain
Audio (DDC)	volume, mute
Mode & Resolution	resolution, refresh rate, HiDPI, color depth, mode list
HDR & XDR	HDR toggle, XDR preset + reset
Physical & Layout	rotation, placement, move-to, underscan, gaussian blur, backlight, power off
DDC	raw VCP read/write, capabilities
Connection & Input	connected, change input source, connection mode
CEC & Remote	send CEC, remote keys, CEC report
Color Profile	select / reset color profile, list installed
Protection	protect resolution / refresh / HDR / rotation / profiles (some Pro)
Mirror	mirror to another display
PIP (Pro)	picture-in-picture toggle and geometry
Stream (Pro)	display streaming controls
EDID	custom / factory EDID, auto-apply
Framebuffer	standard / inverted / grayscale framebuffers, reinitialize
Info & Diagnostics	display info, EDID / DPCD / DSC reports

System settings — Night Shift (+ value), True Tone, Dark Mode, ambient light, OSD options; app UI (menu, settings window, icon, restart, quit); global display management (reconfigure, connect all, disconnect all but main, swap identical); diagnostics (all identifiers JSON); Sidecar.

Virtual screens & groups — create and configure virtual screens (name, serial, aspect, multiplier, HiDPI, resolution list) and manage display groups (enabled, activation policy, synchronization, layout protection, UI scale matching).

How it works

bdui is deliberately modular so each file stays small:

bin/bdui            entry point: locate lib, source modules, run main menu
lib/core.sh         betterdisplaycli wrappers + UI primitives (slider, pick, …)
lib/catalog.sh      the full feature catalog (control type + metadata per feature)
lib/menu_display.sh per-display category menus
lib/menu_system.sh  system-wide + app + global display management
lib/menu_virtual.sh virtual screens + display groups

All display behavior is driven by the catalog + core primitives; the menu files only decide what to show and delegate the rest. Adding a feature is usually a single catalog line.

Credits

• BetterDisplay and betterdisplaycli by @waydabber — bdui is only a front-end for it; all the heavy lifting is BetterDisplay's.
• fzf by @junegunn.

License

MIT — see LICENSE. bdui is an independent project and is not affiliated with or endorsed by BetterDisplay.