Metadata-Version: 2.4
Name: cheatbind
Version: 0.2.0
Summary: Wayland keyboard shortcuts overlay — parses your compositor config and displays a styled cheatsheet
Author-email: Stephane Wetterwald <stephane.wetterwald@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Xhelliom/cheatbind
Project-URL: Issues, https://github.com/Xhelliom/cheatbind/issues
Keywords: wayland,keybindings,overlay,niri,cheatsheet
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: GTK
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Desktop Environment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyGObject>=3.46
Dynamic: license-file

# cheatbind

A Wayland overlay that parses your compositor config and displays a styled keyboard shortcuts cheatsheet.

Instead of maintaining a separate shortcuts list, cheatbind reads your actual config file and renders an overlay with categorized keybindings, 3D keyboard-style key pills, and a multi-column layout.

![cheatbind screenshot](assets/screenshot.png)

## Features

- Auto-parses compositor config — no manual keybinding list to maintain
- Auto-categorizes binds by action type (Applications, Navigation, Workspaces, etc.)
- 3D keyboard-style key pills with multi-column layout
- Live search — type to filter keybindings in real-time
- Merges duplicate keybindings (same action, different keys)
- Toggle behavior — run again to dismiss
- Custom CSS themes via `~/.config/cheatbind/style.css`
- Fade-in animation
- `--dry-run` mode to preview parsed keybindings in terminal

## Supported compositors

- **niri** — parses `~/.config/niri/config.kdl`
- More compositors planned (Hyprland, Sway)

## Install

### Arch Linux (AUR)

```bash
yay -S cheatbind
```

This installs cheatbind and all dependencies (GTK4, gtk4-layer-shell, PyGObject).

### PyPI

```bash
pipx install cheatbind
```

System dependencies must be installed separately:

```bash
# Arch Linux
sudo pacman -S python-gobject gtk4 gtk4-layer-shell

# Fedora
sudo dnf install python3-gobject gtk4 gtk4-layer-shell

# Ubuntu/Debian (24.04+)
sudo apt install python3-gi gir1.2-gtk-4.0 libgtk4-layer-shell-dev
```

### From source

```bash
git clone https://github.com/Xhelliom/cheatbind.git
cd cheatbind
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/cheatbind
```

## Usage

```bash
# Auto-detect compositor and show overlay
cheatbind

# Force a specific compositor
cheatbind --compositor niri

# Use a custom config path
cheatbind --config ~/my-niri-config.kdl

# Preview parsed keybindings in terminal
cheatbind --dry-run
```

Running `cheatbind` while it's already showing will close the overlay (toggle behavior via PID file).

Press **Escape** or click anywhere to dismiss. Type to search/filter keybindings live.

### niri keybinding example

```kdl
Mod+Slash hotkey-overlay-title="Aide raccourcis" { spawn "cheatbind"; }
```

## Config annotations (optional)

You can add markers in your niri config for custom sections and column breaks:

```kdl
binds {
    //##! Applications
    Mod+T hotkey-overlay-title="Terminal" { spawn "alacritty"; }
    Mod+D hotkey-overlay-title="App launcher" { spawn "fuzzel"; }

    //#!
    //##! Navigation
    Mod+Left hotkey-overlay-title="Focus left" { focus-column-left; }

    // [hidden]
    Mod+Secret hotkey-overlay-title="Hidden bind" { do-something; }
}
```

- `//##! Title` — section header
- `//#!` — column break
- `// [hidden]` — exclude a bind from the overlay
- `hotkey-overlay-title=null` — also excludes a bind
- Without markers, cheatbind auto-categorizes binds by action type

## Custom theme

Override the default style by creating `~/.config/cheatbind/style.css`. It is loaded on top of the built-in CSS, so you only need to override what you want to change:

```css
/* Example: different background and accent color */
.overlay { background-color: rgba(20, 20, 40, 0.9); }
.section-title { color: #ff9f43; }
```

### NixOS

```bash
nix run github:Xhelliom/cheatbind
```

## License

MIT
