resctl

A minimal, single-binary CLI for changing display resolution. No dependencies, no installer — just drop the binary in your PATH and go.

Platform	Support
Windows 7 / 8 / 10 / 11	✅ via Win32 API
Linux amd64 (X11)	✅ via xrandr
Linux amd64 (Wayland)	✅ via zwlr-output-management protocol
Linux arm64 (X11 + Wayland)	✅ Raspberry Pi 4/5, Asahi Linux, ARM VMs
macOS	✅ via CoreGraphics

---

Installation

Windows

Option 1 — Download a release (recommended)

1. Grab resctl.exe from the latest release.

2. Optionally verify the download against checksums.txt (also in the release assets):

   # PowerShell
   $hash = (Get-FileHash resctl.exe -Algorithm SHA256).Hash.ToLower()
   $expected = (Select-String resctl.exe checksums.txt).Line.Split()[0]
   if ($hash -eq $expected) { "OK" } else { "MISMATCH" }

3. Open a terminal in the folder containing the download and run:

   .\resctl.exe install
   

   This copies the binary to %USERPROFILE%\bin\resctl.exe and adds that folder to your user PATH.

4. Restart your terminal — you're done.

Option 2 — Build from source

git clone https://github.com/dever-labs/resctl
cd resctl
.\build.ps1          # installs goversioninfo, embeds resources, builds resctl.exe
.\resctl.exe install

Linux

X11 requires xrandr (x11-xserver-utils on Debian/Ubuntu, xorg-xrandr on Arch).
Wayland works out of the box — the binary speaks the zwlr-output-management-unstable-v1 protocol directly. No extra packages needed. Requires a compositor that implements that protocol (e.g. sway, wayfire, labwc, or any wlroots-based compositor).

Option 1 — Download a release (recommended)

1. Grab the binary for your architecture from the latest release:

   • resctl — amd64 (most desktops/laptops)
   • resctl-linux-arm64 — arm64 (Raspberry Pi 4/5, Asahi Linux, ARM cloud VMs)

2. Optionally verify the download against checksums.txt (also in the release assets):

   sha256sum -c checksums.txt --ignore-missing
   # resctl: OK

3. Run:

   chmod +x resctl
   ./resctl install

   This copies the binary to ~/bin/resctl and adds ~/bin to your PATH in .bashrc, .zshrc, or .profile.

4. Restart your terminal — you're done.

Option 2 — Build from source

git clone https://github.com/dever-labs/resctl
cd resctl
go build -ldflags="-s -w" -o resctl .
./resctl install

macOS

Option 1 — Download a release (recommended)

1. Grab resctl-macos from the latest release.

2. Optionally verify the download against checksums.txt (also in the release assets):

   sha256sum -c checksums.txt --ignore-missing
   # resctl-macos: OK

3. Run:

   mv resctl-macos resctl
   chmod +x resctl
   ./resctl install

   This copies the binary to ~/bin/resctl and adds ~/bin to your PATH in .bash_profile, .zshrc, .config/fish/config.fish, or .profile.

4. Restart your terminal — you're done.

Option 2 — Build from source

git clone https://github.com/dever-labs/resctl
cd resctl
go build -ldflags="-s -w" -o resctl .
./resctl install

Uninstall

resctl uninstall

---

Usage

resctl list                    List all supported resolutions (current marked with *)
resctl get                     Show the current resolution
resctl set <WxH[@Hz]>          Change resolution
resctl toggle [res1 res2 ...]  Cycle between resolutions
resctl install                 Copy binary to ~/bin and add to PATH
resctl uninstall               Remove binary from ~/bin
resctl version                 Print the installed version

Resolution format: WxH or WxH@Hz — e.g. 1920x1080 or 2560x1440@144.

Examples

# See everything your monitor supports
resctl list

# What's active right now?
resctl get

# Switch to 1080p (keeps the current refresh rate if available)
resctl set 1920x1080

# Switch to 1440p at 144 Hz explicitly
resctl set 2560x1440@144

# Set up a two-resolution toggle and switch immediately
resctl toggle 1920x1080 2560x1440

# After that, each call to `toggle` cycles to the next entry
resctl toggle

Toggle state is saved and persists across reboots:

• Windows: %APPDATA%\resctl\state.json
• Linux: $XDG_CONFIG_HOME/resctl/state.json (defaults to ~/.config/resctl/state.json)
• macOS: ~/Library/Application Support/resctl/state.json

---

How it works

• Windows — calls EnumDisplaySettingsW and ChangeDisplaySettingsW directly. No admin rights required for the primary display.
• Linux (X11) — shells out to xrandr. Targets the primary connected output. Requires an X11 session.
• Linux (Wayland) — connects to the Wayland compositor socket and speaks the zwlr-output-management-unstable-v1 protocol natively. No external tools required. The session is detected automatically via WAYLAND_DISPLAY or XDG_SESSION_TYPE.
• macOS — calls CoreGraphics (CGDisplayCopyDisplayMode, CGDisplayCopyAllDisplayModes, and CGDisplaySetDisplayMode) directly for the main display. No external tools required.

---

Development

The easiest way to get started is with the included Dev Container — open the repo in VS Code or GitHub Codespaces and everything is set up automatically.

Requirements (without Dev Container)

• Go 1.20+
• Windows build: goversioninfo (go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@latest)
• Linux build: xrandr for smoke-testing
• macOS build: Xcode Command Line Tools for cgo and CoreGraphics

Build

Windows:

.\build.ps1

Or manually:

go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@latest
goversioninfo -64 -o resource.syso   # embed icon & version metadata
go build -ldflags="-s -w -X main.version=dev" -o resctl.exe .

Linux:

go build -ldflags="-s -w -X main.version=dev" -o resctl .

macOS:

go build -ldflags="-s -w -X main.version=dev" -o resctl .

Cross-compile for Windows from Linux (Dev Container):

GOOS=windows GOARCH=amd64 go build -ldflags="-s -w -X main.version=dev" -o resctl.exe .

Test

Tests run without resource.syso present (the test linker cannot handle Windows COFF resource objects):

# Windows
Remove-Item resource.syso -ErrorAction SilentlyContinue
go test ./...

# Linux / Dev Container
go test ./...

# macOS
go test ./...

Release

Tag the commit you want to release, then create a release from the GitHub UI and attach the built binary as an asset:

$env:VERSION = "v1.0.0"
.\build.ps1

---

License

MIT © Dever Labs