xtmonctl

xtmonctl is a Linux command-line and terminal UI tool for controlling the brightness of external monitors through ddcutil and DDC/CI.

It is aimed at people who live in the terminal and want a straightforward way to manage monitor brightness without opening a desktop settings panel every time. The most natural audience is Arch Linux, Debian, Ubuntu, Fedora, and similar desktop users who already install command-line tools, use external monitors, and are comfortable with package-manager setup steps when hardware access is involved.

Screenshot

What It Is Good For

• External monitor brightness control from the terminal
• Keyboard-driven brightness adjustments in a TUI
• Shell scripting and automation with plain text or JSON output
• Managing multi-monitor setups with friendly aliases
• Linux desktop users who want a small native binary instead of a Python toolchain

What It Does Not Guarantee

xtmonctl does not work with every screen on every Linux system.

It depends on:

• Linux
• ddcutil
• a monitor that supports DDC/CI
• a cable and GPU path that actually passes DDC/CI traffic
• permission to access I2C devices

Internal laptop panels usually do not work through DDC/CI. Some adapters, docks, KVMs, HDMI splitters, and unusual GPU drivers can also break DDC/CI support even when the monitor itself is capable.

Support Matrix

Officially targeted environment:

• OS: Linux
• Monitor type: external monitors with DDC/CI support
• Interface: HDMI, DisplayPort, DVI, VGA where DDC/CI is exposed correctly
• Shell use: supported
• TUI use: supported

Best-supported distributions:

• Arch Linux and Arch-based distributions
• Debian and Ubuntu
• Fedora

Not currently targeted:

• macOS
• Windows
• internal laptop brightness control

Features

• Interactive TUI
• Slash-command palette inside the TUI
• Scriptable CLI
• Multi-monitor support
• Honest percentage reporting when the monitor max is not 100
• Alias-aware monitor lookup
• YAML configuration
• JSON output for scripting
• In-app theme switching
• Release binaries for direct installation

Installation

Option 1: Install the latest release binary

This is the simplest way to install it like a normal terminal program.

curl -fsSL https://github.com/ThorOdinson246/xmonctl-rs/releases/latest/download/xtmonctl-x86_64-unknown-linux-gnu.tar.gz -o xtmonctl.tar.gz
tar -xzf xtmonctl.tar.gz
install -Dm755 xtmonctl "$HOME/.local/bin/xtmonctl"

Make sure $HOME/.local/bin is on your PATH.

Option 2: Use the interactive installer

./scripts/install.sh
./scripts/install.sh --from-release

--from-release prefers the latest GitHub release binary. Without it, the script installs from the local source tree with Cargo.

Option 3: Install from source with Cargo

cargo install --path .

Distribution-Specific Setup

Arch Linux

Install system requirements:

sudo pacman -S ddcutil rustup
rustup default stable
rustup component add rustfmt clippy

Build and install locally:

cargo install --path .

There is also an Arch packaging helper at packaging/arch/PKGBUILD if you want to turn it into a package with makepkg.

Debian and Ubuntu

Install system requirements:

sudo apt update
sudo apt install -y ddcutil curl build-essential pkg-config dpkg-dev

Install from release:

./scripts/install.sh --from-release

Build a local .deb package:

./packaging/debian/build-deb.sh
sudo apt install ./xtmonctl_0.1.1_amd64.deb

Fedora

Install system requirements:

sudo dnf install -y ddcutil rust cargo

Then install from source:

cargo install --path .

Required System Access

For non-root use, your system usually needs:

• the i2c-dev kernel module
• udev rules allowing access to /dev/i2c-*
• a session restart after group or permission changes

The installer script helps configure these, but the exact setup depends on your distribution.

Usage

Start the TUI

xtmonctl

TUI Highlights

• j / k or arrow keys move between monitors
• h / l adjust brightness by the configured step size
• H / L use the larger configured step size
• 0-9 apply preset brightness levels
• t cycles themes
• r refreshes monitor detection and brightness reads
• Tab opens the command palette
• /status, /controls, /presets, /help, /theme, /hide are available in the palette
• Short aliases like /s, /c, /p, /h, /t, and /x work too

CLI Commands

xtmonctl list
xtmonctl list --json
xtmonctl get 1
xtmonctl get "Main Monitor"
xtmonctl set 1 70
xtmonctl set 1 +10
xtmonctl all 40
xtmonctl alias list
xtmonctl alias set 1 "Main Monitor"
xtmonctl alias clear 1
xtmonctl config path

JSON Output

Examples:

xtmonctl list --json
xtmonctl get 1 --json
xtmonctl alias list --json

This is useful when integrating xtmonctl into shell scripts, window manager hooks, or custom desktop widgets.

Configuration

Default config path:

~/.config/xtmonctl/config.yaml

Override it with:

xtmonctl --config /path/to/config.yaml list

Example config:

monitors:
  i2c-4:
    alias: Main Monitor
    last_brightness_percent: 70
default_step_percent: 5
large_step_percent: 10
detection_timeout_secs: 15
command_timeout_secs: 5

Release and Packaging

GitHub Releases

Pushing a tag like v0.1.1 triggers the release workflow, which uploads:

• xtmonctl-x86_64-unknown-linux-gnu.tar.gz

Arch Packaging

Use:

cd packaging/arch
makepkg -si

Debian Packaging

Use:

./packaging/debian/build-deb.sh
sudo apt install ./xtmonctl_0.1.1_amd64.deb

Troubleshooting

No monitors detected

Check:

• that the monitor supports DDC/CI
• that DDC/CI is enabled in the monitor menu
• that your cable or dock passes DDC/CI
• that ddcutil detect works directly

Permission denied

You probably need I2C access configured for your user. Re-run:

./scripts/install.sh

The monitor is listed but brightness reads fail

That usually means the monitor is visible but DDC/CI communication is unreliable on the current cable, dock, GPU output, or adapter path.

Development

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo build --release

Current Status

xtmonctl is usable now for Linux users with supported external monitors, but it should still be treated as an early-stage hardware utility rather than a guaranteed universal monitor tool. If your setup is a common Linux desktop with standard HDMI or DisplayPort external displays, it should be a good fit. If your setup relies on unusual docks, KVMs, laptop internal panels, or proprietary GPU edge cases, expect some trial and error.