---
name: "ratbagctl"
section: "1"
platform: "linux"
package: "libratbag"
version: "0.18-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ratbagctl"
---

# ratbagctl(1)

inspect and modify configurable mice

## NAME

ratbagctl - inspect and modify configurable mice

## SYNOPSIS

**ratbagctl** \[\<*options*\>\] **list**\
 **ratbagctl** \[\<*options*\>\] \<*device*\> \<*command*\> ...

## DESCRIPTION

The **ratbagctl** tool queries or changes a device's settings.

This tool usually needs ratbagd to be running.

## OPTIONS

- **--version, -V**

  Show program's version number and exit.

- **--verbose, -v**

  Print debugging output. Multiple -v options increase the verbosity. For example, **-vvv** will show the protocol output.

- **--nocommit**

  Do not immediately write the settings to the mouse. This allows multiple parameters to be set in a script, and the last call to **ratbagctl** will write them all.

- **--help, -h**

  Print the help.

## General Commands

- **list**

  List supported devices (does not take a device argument)

## Device Commands

- **info**

  Print information about a device

- **name**

  Print the device name

## 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

**Available COMMANDs:**

- **get**

  Print selected profile information

- **name get**

  Print the name of the profile

- **name set blah**

  Set the name of the profile

- **enable**

  Enable a profile

- **disable**

  Disable a profile

- **\[resolution\|dpi\|rate\|button\|led\] ...**

  Use profile N for the specified 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 default get**

  Print the current default resolution

- **resolution default set N**

  Set resolution N as the default resolution

- **resolution N {COMMAND}**

  Use resolution N for COMMAND

**Available COMMANDs:**

- **get**

  Print selected resolution

- **\[dpi\|rate\] ...**

  Use resolution N for the specified 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 get-all**

  Print the supported dpi values

- **dpi set N**

  Set the dpi value to N

## Rate Commands

Rate commands work on the given profile and resolution, or on the active resolution of the active profile if none are given.

- **rate get**

  Print the report rate in ms

- **rate get-all**

  Print the supported report rates in ms

- **rate set N**

  Set the report rate in N ms

## 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 get**

  Print the selected button

- **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-event-codes.h key names.

- **KEY\_A**

  Press and release 'a'

- **+KEY\_A**

  Press 'a'

- **-KEY\_A**

  Release 'a'

- **t300**

  Wait 300ms

## LED Commands

LED commands work on the given profile, or on the active profile if none is given.

- **led get**

  Print the current led values

- **led N get**

  Print the selected LED value

- **led N {COMMAND}**

  Use led N for COMMAND

**Available COMMANDs:**

- **mode \[on\|off\|cycle\|breathing\]**

  The mode to set as current

- **color RRGGBB**

  The color to set as current (the color should be in the hexadecimal format).

- **rate R**

  The rate to set as current

- **brightness B**

  The brightness to set as current

## Examples

- ratbagctl profile active get eventX

  - ratbagctl profile 0 resolution active set 4 eventX

  - ratbagctl profile 0 resolution 1 dpi get eventX

  - ratbagctl resolution 4 rate get eventX

  - ratbagctl dpi set 800 eventX

  ## NOTES

There is currently no guarantee that the output format of **ratbagctl** 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.

## AUTHORS

**ratbagctl** was written by David Herrmann, Peter Hutterer and Benjamin Tissoires.

This manual page was written by Stephen Kitt \<skitt@debian.org\> for the Debian GNU/Linux system (but may be used by others).