gnome-randr-rust

gnome-randr is a GNOME Wayland display-management CLI built on org.gnome.Mutter.DisplayConfig.

It targets capability parity with the useful parts of xrandr, not argument compatibility with RandR.

Install

Requirements:

• cargo
• pkg-config

Published crate:

cargo install gnome-randr

Current checkout:

cargo install --path .

Custom prefix:

cargo install --path . --root /your/prefix

The installed binary name is gnome-randr.

Completions:

gnome-randr completions bash
gnome-randr completions zsh
gnome-randr completions fish

Capabilities

• text and JSON query
• mode, refresh, scale, primary, enable/disable
• absolute and relative placement
• mirroring with --same-as
• rotation and reflection
• typed monitor properties such as --color-mode
• software brightness and software gamma
• native layout mode, power-save, backlight, and luminance controls
• saved layout restore with apply FILE

Completed roadmap:

• docs/addressed/notes/0000_xrandr_capability_parity_routing.md
• docs/addressed/notes/0000_align_native_surface_with_gdctl_routing.md

Common Commands

Inspect state:

gnome-randr query
gnome-randr query --summary
gnome-randr query --json
gnome-randr query eDP-1 --verbose

Change layout:

gnome-randr modify eDP-1 --mode 1920x1080 --refresh 60
gnome-randr modify HDMI-1 --right-of eDP-1
gnome-randr modify HDMI-1 --same-as eDP-1
gnome-randr modify HDMI-1 --off

Preview without applying:

gnome-randr modify eDP-1 --scale 2 --dry-run

Persistent Layouts

Use --persistent when you want a layout change to survive reboot. The CLI still applies the change live through Mutter, and it also writes GNOME's monitors.xml in the user config directory so the layout can be restored on the next login.

Software Color

Software color uses the current compositor-installed LUT as baseline.

Brightness:

gnome-randr modify eDP-1 --brightness 1.25 --filter filmic

Gamma:

gnome-randr modify eDP-1 --gamma 1.1
gnome-randr modify eDP-1 --gamma 1.1:1.0:0.9

Composition order:

• gamma first
• brightness/filter second

query reports both software_brightness and software_gamma.

Native Controls

These are distinct from software brightness/gamma:

gnome-randr modify --layout-mode logical
gnome-randr modify --power-save off
gnome-randr modify eDP-1 --backlight 80
gnome-randr modify eDP-1 --luminance 90
gnome-randr modify eDP-1 --reset-luminance

Reflection And Typed Properties

Reflection:

gnome-randr modify eDP-1 --reflect x
gnome-randr modify eDP-1 --reflect xy

Typed property control:

gnome-randr modify eDP-1 --color-mode default
gnome-randr modify eDP-1 --color-mode bt2100

query exposes typed:

• rotation
• reflection
• color_mode
• supported_color_modes
• is_for_lease
• is_underscanning

query --properties still exposes the raw property maps.

Leasing

gnome-randr supports Mutter's typed monitor leasing surface.

gnome-randr modify --for-lease-monitor DP-2 --dry-run

• leased monitors are removed from any active logical monitor in the applied config
• leasing is sent through the top-level monitors-for-lease property in ApplyMonitorsConfig
• query and query --json expose typed is_for_lease

Saved Layouts

The saved layout format is the same schema returned by query --json.

gnome-randr query --json > work-layout.json
gnome-randr apply work-layout.json --dry-run
gnome-randr apply work-layout.json

Matching uses monitor identity (vendor, product, serial), not connector name alone.

JSON Output

Current schema version: 8.

Top-level structure:

• display metadata and native display state
• logical_monitors
• monitors

logical_monitors include geometry, typed rotation/reflection, primary flag, and attached monitor identities.

monitors include identity, enabled state, typed lease state, modes, typed monitor properties, native backlight/luminance state, and software color state.

Examples:

# native display state
gnome-randr query --json | jq '{layout_mode, power_save_mode, night_light_supported}'

# software color state
gnome-randr query eDP-1 --json | jq '.monitors[0] | {software_brightness, software_gamma}'

# typed reflection and monitor properties
gnome-randr query --json | jq '.logical_monitors[] | {rotation, reflection, monitors}'
gnome-randr query --json | jq '.monitors[] | {connector, color_mode, supported_color_modes, is_for_lease, is_underscanning}'

# native backlight and luminance
gnome-randr query --json | jq '.monitors[] | {connector, hardware_backlight_supported, hardware_backlight, luminance_preferences}'

Backend Limits

Not supported with the current backend:

• custom modelines or arbitrary mode injection
• arbitrary transform matrices or panning
• framebuffer and DPI compatibility flags
• X11 provider and explicit CRTC controls
• generic raw X11-style property setting

Some operations are backend-limited even when the CLI supports them, especially:

• partial mirroring in some layouts
• some layout-mode transitions
• some native power-save and backlight behavior

If a mode is missing from query, Mutter did not expose it.

Method

gnome-randr-rust uses the dbus object org.gnome.Mutter.DisplayConfig. See https://wiki.gnome.org/Initiatives/Wayland/Gaps/DisplayConfig for the original proposal, although the specification listed there is somewhat out of date (checked via dbus introspect on Gnome shell 40.5). Gnome maintain the evolving XML file here.

• GetCurrentState for inspection
• ApplyMonitorsConfig for layout changes
• native Mutter setters for power-save, backlight, and luminance where available

Inspiration

• xrandr
• gnome-randr

Alignment With gdctl

gdctl is the upstream Mutter CLI for the same org.gnome.Mutter.DisplayConfig backend. gnome-randr now uses it as the native reference for terminology, enums, capability boundaries, and backend expectations.

Native surface aligned with gdctl:

• show / set / --verify aliases for query / modify / --dry-run
• layout mode, placement, same-as mirroring, rotation, reflection, mode, scale, and primary controls
• typed monitor properties such as color-mode, rgb-range, and for-lease-monitor
• native power-save, backlight, and luminance controls

Intentional differences:

• gnome-randr keeps the higher-level query / modify / apply FILE model instead of cloning gdctl syntax wholesale
• query --json, software brightness/gamma, saved layout restore, and shell completions are higher-level features beyond gdctl
• aliases are additive only where semantics actually match cleanly

Reference notes:

• docs/addressed/notes/0000_align_native_surface_with_gdctl_routing.md
• docs/addressed/notes/0010_publish_gdctl_compatibility_matrix_and_divergence_policy.md