mx4

Tiny CLI for MX Master 4 status and settings.

Installation

cargo install mx4

Requirements

Cargo builds mx4 from source. It requires a current stable Rust toolchain, a C build toolchain, pkg-config, and the libudev development files on Linux. On Debian or Ubuntu, install the native build dependencies with:

sudo apt install build-essential pkg-config libudev-dev

Cargo places the binary in ~/.cargo/bin. Make sure that directory is included in PATH.

Install the Debian package

Download the amd64 .deb from the GitHub release you want to install, then run:

sudo apt install ./mx4_*_amd64.deb

The package contains a prebuilt binary and the udev access rule. APT installs its runtime dependencies automatically, so Rust, build-essential, pkg-config, and libudev-dev are not required.

To uninstall, remove the opt-in per-user daemon before purging the package:

mx4 daemon --uninstall
sudo apt purge mx4

APT does not remove files generated in a user's home directory. If the package was purged before the daemon was uninstalled, clean up the remaining user service with:

systemctl --user disable --now mx4.service
rm -f ~/.config/systemd/user/mx4.service
systemctl --user daemon-reload
systemctl --user reset-failed mx4.service

Install from source

git clone https://github.com/EriksRemess/mx4.git
cd mx4
cargo install --path .

Run from source without installing

cargo run --release -- --help
cargo run --release -- status
cargo run --release -- firmware --json

The first -- separates Cargo's arguments from arguments passed to mx4. To build once and run the resulting binary directly:

cargo build --release
./target/release/mx4 --help

Tests

cargo test
cargo test hardware -- --ignored --nocapture

Normal tests require no mouse. The opt-in hardware tests require an awake MX Master 4 connected over Bolt or Bluetooth, HID access, and a writable configuration directory. They read all status features and firmware, check repeated concurrent DPI/haptic queries from separate CLI processes, and send haptic effect 14 through the CLI. Leave settings unchanged while they run; the daemon can remain active.

Hardware tests fail if the mouse is unavailable or a command fails. The playback test checks that the effect command sends successfully and leaves the haptic configuration unchanged. Playback has no acknowledgement, so feel the mouse during the test to confirm physical vibration. Tests use the current haptic strength without changing settings.

Library

This crate can also be used as a Rust library:

use mx4::features;

fn main() -> mx4::Result<()> {
    let battery = features::battery::read_status()?;
    println!("{} {}", battery.pct, battery.charging);
    Ok(())
}

Usage

mx4 status
mx4 status --json
mx4 status battery
mx4 status battery --json
mx4 status dpi
mx4 status dpi --json
mx4 status wheel
mx4 status wheel --json
mx4 status thumb-wheel
mx4 status thumb-wheel --json
mx4 status force-button
mx4 status force-button --json
mx4 status haptic
mx4 status haptic --json
mx4 set host 2
mx4 set dpi 2500
mx4 set strength 100
mx4 set strength off
mx4 set wheel ratchet free
mx4 set wheel ratchet-speed 10
mx4 set wheel force 75
mx4 set wheel invert on
mx4 set wheel resolution off
mx4 set wheel divert off
mx4 set thumb-wheel invert off
mx4 set thumb-wheel divert on
mx4 set force-button 4310
mx4 daemon
mx4 daemon --install
mx4 daemon --once
mx4 daemon --uninstall
mx4 haptic 14
mx4 haptic 0..3
mx4 haptic '{0..14}'
mx4 battery
mx4 battery --json
mx4 firmware
mx4 firmware --json

Haptic strength presets:

• off = 0
• subtle = 15
• low = 45
• medium = 60
• high = 100

Background daemon

The daemon is opt-in. Normal status and setting commands never install or start a background service.

Install the binary first, then install and start the per-user service:

mx4 daemon --install

This creates a user systemd service on Linux or a user launchd agent on macOS. It watches for reconnects and reapplies saved settings. No sudo is needed.

The CLI and daemon coordinate device access through a lock file in the configuration directory. Both must use the same configuration directory, which must be writable even for status queries.

Other daemon modes:

mx4 daemon             # run in the foreground
mx4 daemon --once      # apply saved settings once and exit
mx4 daemon --uninstall # stop and remove the background service

Linux permissions

The Debian package installs and reloads the udev access rule automatically. For Cargo or source installations, if a targeted command such as mx4 status dpi reports a /dev/hidraw... Permission denied error, install the rule once and reconnect the mouse or Logi Bolt receiver:

sudo install -Dm644 contrib/udev/70-mx4.rules /etc/udev/rules.d/70-mx4.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

The source checkout already contains that rule. A Cargo installation only installs the binary, so download the rule first if you do not have the source tree:

curl -fLO https://raw.githubusercontent.com/EriksRemess/mx4/main/contrib/udev/70-mx4.rules
sudo install -Dm644 70-mx4.rules /etc/udev/rules.d/70-mx4.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

sudo mx4 status can confirm that the HID++ device is readable, but it is only a diagnostic. Normal use should not need sudo after the udev rule is active.

Notes:

• mx4 status prints battery, DPI, wheel, thumb-wheel, force-button, and haptic state when available.
• mx4 status --json prints all readable status values as one JSON object, using null for unavailable features.
• mx4 status haptic prints the configured haptic level when the device exposes it.
• mx4 battery remains as a shorter alias for battery status.
• mx4 firmware prints the mouse firmware entities and Bolt receiver firmware when available.
• Persistent mx4 set ... commands save the applied value to a local config file so it can be restored later.
• mx4 set host ... and mx4 haptic ... do not persist anything.
• mx4 daemon polls for reconnects and reapplies saved settings when the mouse comes back.
• The background service is only installed when mx4 daemon --install is run explicitly.
• The saved config file lives at:
  • Linux: ~/.config/mx4/config.toml unless XDG_CONFIG_HOME is set
  • macOS: ~/Library/Application Support/mx4/config.toml