RIVER(1)

💅 RIVER(1) — the manual page, but make it make sense ✨

okay so real talk, you're looking at the General Commands Manual entry for river, and bestie, you're gonna want to sit down for this one because it's giving iconic 🌈

---

🦋 NAME 🦋

river — a non-monolithic Wayland compositor, and yes the "non-monolithic" part is the whole personality 🎀

---

✨ SYNOPSIS ✨

river [options]

that's it. that's the whole vibe check. optional flags, one binary, go off 👑

---

💖 DESCRIPTION 💖

So. river is a non-monolithic Wayland compositor, which lowkey means it does not shove the compositor and the window manager into one single program like some other projects do 🙈 nope, not here. Instead, you — yes you — can pick any window manager implementing the river-window-management-v1 protocol. main character energy, you choose your own adventure 💅

Which brings us to the important part, and I need you to hear me on this: river is not useful without a compatible window manager. fr fr. it's the compositor, it needs its wm bestie to actually do the window things 🫶

There's a whole list of compatible window managers on the river wiki, go look:

https://codeberg.org/river/wiki/src/branch/main/pages/wm-list.md

---

🔥 OPTIONS 🔥

• -h — prints a help message and then dips. classic. exits immediately ✌️
• -version — prints the version number and exits. no cap, that's all it does 💀
• -c shell_command — overrides the default search paths for an init executable; instead, shell_command gets run with /bin/sh -c. peek at the CONFIGURATION section below for the deets, iykyk 🧚
• -log-level [error|warning|info|debug] — sets the log level of river. At the error log level, only errors are logged. At the debug log level, literally everything is logged, including verbose debug messages 🔍 (yes she's chatty, that's the point)
• -no-xwayland — disables Xwayland at runtime, even if river has been built with support for it. turn it off, turn it all the way off 🙅‍♀️

---

🎀 KEYBINDINGS 🎀

These ones below are always active, no matter what:

• Ctrl+Alt+F1 – Ctrl+Alt+F12 — switch to VT 1-12 🖥️✨

⚠️ ok so heads up: window managers may add additional keybindings, but they cannot override these builtin keybindings. them's the rules, periodt 💅

---

🌸 CONFIGURATION 🌸

On startup, river will run an executable file at $XDG_CONFIG_HOME/river/init — but only if such an executable actually exists, okurrr? 💖 If $XDG_CONFIG_HOME is not set, then ~/.config/river/init gets used instead. either way, she will find you 🦋

Here's the cute part: that executable init file is run as a process group leader after river's Wayland server is initialized, but before entering the main loop. and on exit, river will send SIGTERM to this process group. clean up after yourself bestie 🧹

Usually this executable is a shell script which starts the user's window manager plus any other long-running programs. for example, kanshi(1) could be started to manage output configuration 🌈 — that's it, that's the whole config story, surprisingly chill ngl

---

👑 AUTHORS 👑

Maintained by Isaac Freund <mail@isaacfreund.com>, who is assisted by open source contributors 🫶. For more information about river's development, see:

https://isaacfreund.com/software/river

---

💜 also we literally cannot forget the fine print: this page is from 2026-10-10 and the source/version tag is RIVER(1) — so yeah, dated October 10, 2026, file it under "iconic", and go configure your compositor bestie 🎀💖✨