WonKey

One-key keyboard configuration for Linux

One key,
to rule them all.

Configure your XFKEY One Key Max on Linux. Set the key combination, choose the RGB lighting, and restore saved settings.

Get WonKey Quick start

Open source. Linux only. XFKEY One Key Max model 0112.

wonkey · Linux
# Set your key combination
$ wonkey key ctrl+shift+f13

# Choose static blue
$ wonkey rgb static 0000ff

# Restore saved settings
$ wonkey restore

Features

Make it yours

Control your key and lighting from the terminal. WonKey previews each change and asks before it saves.

Explore the Wiki
Your key combination
Choose one key: Enter, A to Z, 0 to 9, or F1 to F24. Add optional Ctrl, Shift, Alt, and Super modifiers. Names ignore case and do not imply Shift. Letters and digits name HID keys, not text: the active host layout and modifiers determine the output. Set the trigger with --on. Letters, digits, F1 to F12, and F14 to F24 remain unverified on hardware.
Your RGB lighting
Choose the lighting mode. static, breathe, flash, held, and toggle accept an optional colour: six hexadecimal digits without #. Omit the colour to preserve it. cycle-slow, cycle-fast, and off do not use a colour and reject supplied colours. RGB changes preserve your key settings.
Your saved settings
Restore a compatible backup with wonkey restore. WonKey restores key and RGB settings while preserving other current configuration bytes.

Everyday shortcuts

Mute a meeting. Dictate a thought.

Choose one of these alternatives. WonKey stores one key combination at a time.

Google Meet

Toggle your microphone in Google Meet.

wonkey key ctrl+d --on press

Keep the meeting page focused. Check Ctrl+D in your Linux browser first.

Google Meet shortcuts

Zoom

Toggle your microphone in the Linux desktop app.

wonkey key alt+a --on press

Keep the Zoom app focused.

Zoom shortcuts

Handy

Press to record. Press again to transcribe.

wonkey key ctrl+shift+h --on press

In Handy, set the transcription shortcut to Ctrl+Shift+H. Turn off Push To Talk for toggle mode.

On Wayland, follow Handy's desktop shortcut setup.

Handy settings

How it works

See the change before you save

Read settings at any time. Changes require a terminal, your confirmation, and a validated automatic backup.

  1. wonkey key

    Read your settings

    Bare key and rgb commands show the current settings without changing them or creating backups.

  2. wonkey key f13 --on release

    Choose your change

    Set a complete key combination. Omit --on to keep the current trigger, or omit an RGB colour to keep it.

  3. Save settings? [Y/n]:

    Check and confirm

    Review the selected device and current-to-proposed settings. Press Enter to save, or enter n to cancel.

  4. wonkey restore

    Keep a way back

    WonKey validates a fresh backup before each write and checks the result. Restore lets you choose saved settings later.

Cancellation and unchanged settings create no backup and send no settings writes. Restore changes settings, not firmware.

Install

Get WonKey on Linux

Install WonKey 0.1.1 with your Linux package manager. Choose a download for x86_64 or ARM64.

Compare downloads with the SHA-256 checksums before installation.

After installation, run wonkey --help. Help does not access the device.

WonKey needs access to the device's vendor hidraw node. WonKey does not install permission rules. See the Wiki for hardware setup and all options.

Debian / Ubuntu

Download the .deb, then run its command from the download directory.

x86_64 package

sudo apt install ./wonkey_0.1.1_linux_amd64.deb

ARM64 package

sudo apt install ./wonkey_0.1.1_linux_arm64.deb
Fedora

Download the .rpm, then run its command from the download directory.

x86_64 package

sudo dnf install ./wonkey_0.1.1_linux_amd64.rpm

ARM64 package

sudo dnf install ./wonkey_0.1.1_linux_arm64.rpm
openSUSE

Download the .rpm, then run its command from the download directory.

x86_64 package

sudo zypper install ./wonkey_0.1.1_linux_amd64.rpm

ARM64 package

sudo zypper install ./wonkey_0.1.1_linux_arm64.rpm
Alpine

Download the .apk, then run its command from the download directory. The package is unsigned, so apk requires --allow-untrusted.

x86_64 package

sudo apk add --allow-untrusted ./wonkey_0.1.1_linux_amd64.apk

ARM64 package

sudo apk add --allow-untrusted ./wonkey_0.1.1_linux_arm64.apk
Arch Linux (AUR)

Install xfkey-wonkey-bin from the AUR. Requires yay.

yay -S xfkey-wonkey-bin
Binary archive

Download an archive, then extract and install it from the download directory.

x86_64 archive

tar -xzf WonKey_0.1.1_linux_amd64.tar.gz
sudo install -m 0755 wonkey /usr/local/bin/wonkey

ARM64 archive

tar -xzf WonKey_0.1.1_linux_arm64.tar.gz
sudo install -m 0755 wonkey /usr/local/bin/wonkey
Build from source

Requires Git, Go 1.25 or later, and just.

git clone --branch v0.1.1 --depth 1 https://github.com/wimpysworld/WonKey.git
cd WonKey
just build
sudo install -m 0755 ./wonkey /usr/local/bin/wonkey

The build replaces ./wonkey in the source directory.

Getting started Releases