USAGE.md

MonitorBuddy — Usage Guide

This document provides detailed usage instructions for the MonitorBuddy CLI.

---

Table of Contents

• Overview
• Installation
  • Linux
  • macOS
  • Windows (MSYS2)
• Basic Commands
  • Listing devices
  • Reading properties
  • Setting properties
• Advanced Options
  • VID/PID filters
  • Vendor properties
  • Frame base tuning
  • Dry-run mode
• Examples
• Troubleshooting
• Contributing

---

Overview

Monitorbuddy (mbuddy) is a command-line tool to control monitor settings using DDC/CI over USB HID. It supports both standard VCP codes and vendor‑specific extensions (e.g., Gigabyte/AORUS).

Installation

Linux

sudo apt install libhidapi-dev libudev-dev
go install github.com/leovanalphen/monitorbuddy@latest

macOS

brew install hidapi
CGO_CFLAGS="-I$(brew --prefix hidapi)/include" \
CGO_LDFLAGS="-L$(brew --prefix hidapi)/lib" \
go install github.com/leovanalphen/monitorbuddy@latest

Windows (MSYS2)

# Ensure MSYS2 UCRT64 toolchain is installed
make win-ucrt64

Basic Commands

Listing devices

mbuddy -list

Reading properties

mbuddy -get brightness -mon 0

Setting properties

mbuddy -set brightness -val 50 -mon 0

Advanced Options

VID/PID filters

mbuddy -list -vid 0x0bda -pid 0x1100

Vendor properties

Enable/disable vendor properties:

mbuddy -props -include-gigabyte=false

Frame base tuning

Some monitors require a different frame length base:

mbuddy -set brightness -val 20 -frame-base 0x80

Dry-run mode

mbuddy -set brightness -val 30 -n

Examples

• Set brightness on multiple monitors:

mbuddy -set brightness -val 70 -mon 0,1

• Read firmware level:

mbuddy -get fw-level -mon 0

Troubleshooting

• No devices found: try -vid 0 -pid 0 and re-run -list.
• Windows build errors: ensure MSYS2 UCRT64 gcc is installed.
• Monitor not responding: verify USB upstream cable is connected.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.