cagebreak(1)

📦
version 3.2.0 · 4 versions
, in alpine 3.24

💅 cagebreak(1) — the Cagebreak Manual, bestie edition 🦋

okay so picture this: you're on a Wayland session, your windows are chaos, and you want a compositor that just gets you. That's cagebreak. This is the cagebreak manual page, and I'm gonna walk you through literally every single thing on it, no skips, no cap. ✨

🌸 NAME 🌸

cagebreak — a Wayland tiling compositor. (yes that's the whole name, she's lowkey minimal and iconic for it 💅)

🎀 SYNOPSIS 🎀

cagebreak [OPTIONS]

that's it. that's the whole invocation. gorgeous, unbothered, effortless. 🫶

⭐ DESCRIPTION ⭐

So cagebreak is this slim, keyboard-controlled, tiling compositor for Wayland, and conceptually it's based on the X11 window manager ratpoison. Think of it as ratpoison's cooler younger cousin who went to therapy and learned about workspaces. 💜

It lets you split your screen into non-overlapping tiles — no windows stacked on top of each other, no messy vibes, just clean tiles. And here's the glow-up: in contrast to the original ratpoison, it has native support for multi-workspace operation. multiple workspaces, zero drama. she ate. 🔥

All interactions between you and cagebreak happen via the keyboard. like, all of them. mouse? don't know her. keyboard is the main character here, periodt. 👑

The behaviour gets configured in the $XDG_CONFIG_PATH/cagebreak/config file — go read cagebreak-config(5) for the deets, iykyk. 🎀

Scripting support? oh she's got you. It's provided through the IPC socket specified in the environment variable $CAGEBREAK_SOCKET. The syntax accepted through this socket is identical to that of the configuration file (again: cagebreak-config(5)). And if an error happens during interaction over the IPC channel, it gets displayed in a message box right on your screen — so you literally cannot miss it. 😭💖

✨ OPTIONS ✨

okay bestie, here's the full roster, every single flag, no cuts:

  • -c <path> — loads the configuration file from <path>. your config, your rules. 🎀
  • -e — enables the socket. (yes, that socket, the IPC one 💅)
  • -h — displays the help message and exits. when in doubt, -h it out. 🫶
  • -s — shows all available inputs and outputs. a full vibe check of your hardware. 🌈
  • -v — shows the version number and exits. quick lil flex. ⭐
  • --bs — "bad security". enables features with potential security implications. currently, this option has the following effects (possible implications in parentheses):
    • Prints view titles in dump output (an attacker may be able to read sensitive information contained in the view title). 🚨
ngl the name --bs is sending me, but it is literally called "bad security" for a reason — think before you enable it, bestie. 💀

🌼 ENVIRONMENT 🌼

the environment variables, all of them, in order:

  • CAGEBREAK_SOCKET — the IPC unix domain socket address accepting commands as specified in cagebreak-config(5). 🦋
  • XKB_DEFAULT_LAYOUT — the keyboard layout to be used (see xkeyboard-config(7)).
  • XKB_DEFAULT_MODEL — the keyboard model to be used (see xkeyboard-config(7)).
  • XKB_DEFAULT_VARIANT — the keyboard variant to be used (see xkeyboard-config(7)).
  • XKB_DEFAULT_RULES — the xkb rules to be used.
  • XKB_DEFAULT_OPTIONS — the xkb options to be used.

all your keyboard lore, right there. ⌨️✨

🧚 SEE ALSO 🧚

cagebreak-config(5) cagebreak-socket(7)

go read those next, bestie, they're the lore drops. 📚💜

🐛 BUGS 🐛

Found something cursed? See GitHub Issues: <https://github.com/project-repo/cagebreak/issues> 🌸

Mail contact: cagebreak @ project-repo . co — write it exactly like that, spaces and all, she's quirky like that. 🙈

GPG Fingerprints (the security girlies will know):

  • 0A268C188D7949FEB39FD1462F2AD980247E4918
  • 283D10F54201B0C6CCEE2C561DE04E4B056C749D

📜 LICENSE 📜

Copyright (c) 2020-2024 The Cagebreak authors

Copyright (c) 2018-2020 Jente Hidskes

Copyright (c) 2019 The Sway authors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

okay that's the whole page, you made it to the end, proud of you 🥹💖 — this was Version 3.2.0, dated 2026-04-15, and it's the cagebreak(1) manual page, signed off with love. slay, and happy tiling, bestie. 👑🌸✨

📦 where this page comes from