ratbag-command(1) Query or change a device's settings


ratbag-command [OPTIONS] {COMMAND} ... /path/to/device


The ratbag-commandq tool query or change a device's settings.

This tool usually needs to be run as root to have access to the /dev/input/eventX nodes.


Print debugging output
Print debugging output with protocol output. No guarantees are given regarding the output format when this flag is on.
Print the help.

General Commands

List supported devices (does not take a device argument)

Device Commands

Print information about a device

Profile Commands

profile active get
Print the currently active profile
profile active set N
Set profile N as to the active profile
profile N {COMMAND}
Use profile N for COMMAND

Resolution Commands

Resolution commands work on the given profile, or on the active profile if none is given.
resolution active get
Print the currently active resolution
resolution active set N
Set resolution N as the active resolution
resolution N {COMMAND}
Use resolution N for COMMAND

DPI Commands

DPI commands work on the given profile and resolution, or on the active resolution of the active profile if none are given.
dpi get
Print the dpi value
dpi set N
Set the dpi value to N
rate get
Print the report rate in Hz
rate set N
Set the report rate in N Hz

Button Commands

Button commands work on the given profile, or on the active profile if none is given.
button count
Print the number of buttons
button N action get
Print the button action
button N action set button B
Set the button action to button B
button N action set special S
Set the button action to special action S
button N action set macro ...
Set the button action to the given macro

Macro syntax:

A macro is a series of key events or waiting periods. Keys must be specified in linux/input.h key names.
Press and release 'a'
Press 'a'
Release 'a'
Wait 300ms

Special Commands

These commands are for testing purposes and may be removed without notice
Switch the Etekcity mouse active profile


ratbag-command profile active get
ratbag-command profile 0 resolution active set 4
ratbag-command profile 0 resolution 1 dpi get
ratbag-command resolution 4 rate get
ratbag-command dpi set 800

Exit codes

Unsupported feature or index out of available range
Commandline arguments are invalid
Invalid device or a command failed on the device


There is currently no guarantees that the output format of ratbag-command will not change in the future. There should be some stability with the commands mentioned in this man page, but do not expect it to stay the same.