RIVERCTL(1)

📦
version 0.3.17 · 8 versions
, in arch rolling

💅 RIVERCTL(1) — General Commands Manual 💅

Okay bestie, this is the General Commands Manual for riverctl, and we are keeping every single flag, every argument, every example, and every warning. No cap. 💖

🌸 NAME 🌸

riverctl — command-line interface for controlling river. It's literally the remote control for your compositor. 🎀

✨ SYNOPSIS ✨

riverctl [options] command [command specific arguments]

🦋 DESCRIPTION 🦋

riverctl is a command-line utility used to control and configure river over the Wayland protocol. That's the whole vibe: you say stuff, river listens. 💅

🎀 OPTIONS 🎀

  • -h — Print a help message and exit. Short, sweet, helpful.
  • -version — Print the version number and exit. For when you need to know exactly which era of riverctl you're in.

🧚 TERMINOLOGY 🧚

This manual uses terms that some may find confusing, coming mostly from their usage among other Wayland projects. Don't worry, we're decoding the group chat.

The compositor, display server, Wayland server etc. are ways to refer to river itself. Same energy, different labels.

A view (or toplevel) is what most call a window. Yes bestie, a window by any other name.

An output is a synonym for a screen or monitor. Your display, your stage, your main character rectangle.

Tags are river's way of dividing views of an output into groups (not necessarily disjunct), an analogy to workspaces. Think workspace vibes, but with more flexibility. 🦋

👑 COMMANDS 👑

This is the command menu, and it is stacked. Let's go. 🔥

🔥 ACTIONS 🔥

  • close — Close the focused view. Bye bestie.
  • exit — Exit the compositor, terminating the Wayland session. This is the big red button, fr fr.
  • focus-output next|previous|up|right|down|left|name — Focus the next or previous output, the closest output in any direction or an output by name. Move your attention like it's a vibe check.
  • focus-view [-skip-floating] next|previous|up|down|left|right — Focus the next or previous view in the stack or the closest view in any direction.
    • -skip-floating — Skip floating views, only focusing tiled ones. Floaters can wait their turn.
  • move up|down|left|right delta — Move the focused view in the specified direction by delta logical pixels. The view will be set to floating. Nudge nudge.
  • resize horizontal|vertical delta — Resize the focused view along the given axis by delta logical pixels. The view will be set to floating. Stretch era.
  • snap up|down|left|right — Snap the focused view to the specified screen edge. The view will be set to floating. Magnetic energy.
  • send-to-output [-current-tags] next|previous|up|right|down|left|name — Send the focused view to the next or previous output, the closest output in any direction or to an output by name.
    • -current-tags — Assign the currently focused tags of the destination output to the view. Tag handoff, slay.
  • spawn shell_command — Run shell_command using /bin/sh -c shell_command. Note that spawn only takes a single argument. To spawn a command taking multiple arguments, wrapping the command in quotes is recommended. Quote it or regret it, bestie.
  • swap next|previous|up|down|left|right — Swap the focused view with the next or previous non-floating view in the stack or the closest non-floating view in any direction. Trade places, no cap.
  • toggle-float — Toggle the floating state of the focused view. Float on, float off.
  • toggle-fullscreen — Toggle the fullscreen state of the focused view. Main character full-screen mode.
  • zoom — Bump the focused view to the top of the layout stack. If the top view in the stack is already focused, bump the second view. Priorities, bestie.
  • default-layout namespace — Set the layout namespace to be used by all outputs by default. Default setting, iconic.
  • output-layout namespace — Set the layout namespace of currently focused output, overriding the value set with default-layout if any. This output said "my layout, my rules."
  • send-layout-cmd namespace command — Send command to the layout generator on the currently focused output with the given namespace, if any. What commands a layout generator understands depends on the layout generator. For rivertile, see the documentation in the rivertile(1) man page. Layout generator communication era.

🏷️ TAG MANAGEMENT 🏷️

Tags are similar to workspaces but more flexible. You can assign views multiple tags and focus multiple tags simultaneously. Bitfields are used to describe sets of tags when interfacing with river. As such, the following commands take a normal base 10 number as their argument but the semantics are best understood in binary. The binary number 000000001 represents a set containing only tag 1 while 100001101 represents a set containing tags 1, 3, 4, and 9. It's giving binary baddie. 💅

When a view spawns it is assigned the currently focused tags of the output. New view, current tags, that's the rule.

At least one tag must always be focused and each view must be assigned at least one tag. Operations that would violate either of these requirements are ignored by river. Important caveat bestie — river just ignores those operations.

  • set-focused-tags tags — Show views with tags corresponding to the set bits of tags on the currently focused output. Focus set, slay.
  • set-view-tags tags — Assign the currently focused view the tags corresponding to the set bits of tags. Tag assignment era.
  • toggle-focused-tags tags — Toggle visibility of views with tags corresponding to the set bits of tags on the currently focused output. Toggle toggle.
  • toggle-view-tags tags — Toggle the tags of the currently focused view corresponding to the set bits of tags. Flip the tag bits.
  • spawn-tagmask tagmask — Set a tagmask to filter the tags assigned to newly spawned views. This mask will be applied to the tags of new views with a bitwise and. If, for example, the tags 000011111 are focused and the spawn tagmask is 111110001, a new view will be assigned the tags 000010001. If no tags would remain after filtering, the tagmask is ignored. This is the filter, and yes the example is exact.
  • focus-previous-tags — Sets tags to their previous value on the currently focused output, allowing jumping back and forth between 2 tag setups. Jump back, jump forth.
  • send-to-previous-tags — Assign the currently focused view the previous tags of the currently focused output. Send it back to the previous tag setup.

🖱️ MAPPINGS 🖱️

Mappings are modal in river. Each mapping is associated with a mode and is only active while in that mode. There are two special modes: "normal" and "locked". The normal mode is the initial mode on startup. The locked mode is automatically entered while the session is locked (e.g. due to a screenlocker). It cannot be entered or exited manually. Important: locked mode cannot be entered or exited manually, periodt.

The following modifiers are available for use in mappings:

  • Shift
  • Control
  • Mod1 (Alt)
  • Mod3
  • Mod4 (Super)
  • Mod5
  • None

Alt and Super are aliases for Mod1 and Mod4 respectively. None allows creating a mapping without modifiers. Aliases and no-modifier moves, iykyk.

Keys are specified by their XKB keysym name. See /usr/include/xkbcommon/xkbcommon-keysyms.h for the complete list. That path is exact, bestie.

Mouse buttons are specified by Linux input event code names. The most commonly used values are:

  • BTN_LEFT - left mouse button
  • BTN_RIGHT - right mouse button
  • BTN_MIDDLE - middle mouse button

A complete list may be found in /usr/include/linux/input-event-codes.h Keep that path exactly as-is.

  • declare-mode name — Create a new mode called name. New mode just dropped.
  • enter-mode name — Switch to given mode if it exists. Mode switch, but only if it exists.
  • map [-release|-repeat|-layout index] mode modifiers key command — Run command when key is pressed while modifiers are held down and in the specified mode.
    • -release — if passed activate on key release instead of key press
    • -repeat — if passed activate repeatedly until key release; may not be used with -release
    • -layout — if passed, a specific layout is pinned to the mapping. When the mapping is checked against a pressed key, this layout is used to translate the key independent of the active layout
      • index — zero-based index of a layout set with the keyboard-layout command. If the index is out of range, the -layout option will have no effect
    • mode — name of the mode for which to create the mapping
    • modifiers — one or more of the modifiers listed above, separated by a plus sign (+).
    • key — an XKB keysym name as described above
    • command — any command that may be run with riverctl
  • map-pointer mode modifiers button action|command — Move or resize views or run command when button and modifiers are held down while in the specified mode. The view under the cursor will be focused.
    • mode — name of the mode for which to create the mapping
    • modifiers — one or more of the modifiers listed above, separated by a plus sign (+).
    • button — the name of a Linux input event code as described above
    • action — one of the following values:
      • move-view
      • resize-view
    • command — any command that may be run with riverctl
  • map-switch mode lid|tablet state command — Run command when river receives a certain switch event.
    • mode — name of the mode for which to create the mapping
    • lid|tablet — 'lid switch' and 'tablet mode switch' are supported
    • state:
      • possible states for lid:
        • close
        • open
      • possible states for tablet:
        • on
        • off
    • command — any command that may be run with riverctl
  • unmap [-release] mode modifiers key — Remove the mapping defined by the arguments:
    • -release — if passed unmap the key release instead of the key press
    • mode — name of the mode for which to remove the mapping
    • modifiers — one or more of the modifiers listed above, separated by a plus sign (+).
    • key — an XKB keysym name as described above
  • unmap-pointer mode modifiers button — Remove the pointer mapping defined by the arguments:
    • mode — name of the mode for which to remove the mapping
    • modifiers — one or more of the modifiers listed above, separated by a plus sign (+).
    • button — the name of a Linux input event code as described above
  • unmap-switch mode lid|tablet state — Remove the switch mapping defined by the arguments:
    • mode — name of the mode for which to remove the mapping
    • lid|tablet — the switch for which to remove the mapping
    • state — a state as listed above

🪄 RULES 🪄

Rules match the app-id and title of views against a glob pattern. A glob is a string that may optionally have an * at the beginning and/or end. An * in a glob matches zero or more arbitrary characters in the app-id or title. Glob matching, but make it fashion.

For example, abc is matched by a*, *a*, *b, *c, abc, and * but not matched by *a, b*, *b, c*, or ab. Note that * matches everything while ** and the empty string are invalid. Exact examples, exact invalids — no guessing.

  • rule-add [-app-id glob|-title glob] action [arguments] — Add a rule that applies an action to views with app-id and title matched by the respective glob. Omitting -app-id or -title is equivalent to passing -app-id * or -title *. Some actions require one or more arguments. Rule added, main character behavior installed.

The supported action types are:

  • float — makes the view float. Only applies to new views, bestie ✨
  • no-float — don't make the view float. Only applies to new views.
  • ssd — use server-side decorations for the view. Applies to new and existing views.
  • csd — use client-side decorations for the view. Applies to new and existing views.
  • tags — sets the initial tags of the view. Needs the tags as an argument. Only applies to new views 🏷️
  • output — sets the initial output of the view. Needs the output as an argument. Only applies to new views. You can name the output by connector name (like HDMI-A-1, or DP-2), or by identifier in the form MAKE MODEL SERIAL — for example, for an output with make: HP Inc., model: HP 22w, and serial: CNC93720WF, the identifier would be: HP Inc. HP 22w CNC93720WF. If the make, model, or serial is unknown, the word "Unknown" is used instead. 💅
  • position — sets the initial position of the view, clamping to the bounds of the output. Needs x and y coordinates of the view as arguments, both of which must be non-negative. Only applies to new views.
  • dimensions — sets the initial dimensions of the view, clamping to the constraints of the view. Needs width and height of the view as arguments, both of which must be non-negative. Only applies to new views.
  • fullscreen — makes the view fullscreen. Only applies to new views 👑
  • no-fullscreen — doesn't make the view fullscreen. Only applies to new views.
  • tearing — lets the view tear when fullscreen regardless of the view's preference. Applies to new and existing views.
  • no-tearing — disables tearing for the view regardless of the view's preference. Applies to new and existing views.

Okay so real talk: float and no-float rules both land in the same list, which means adding a no-float rule with the same arguments as a float rule will straight-up overwrite it 😭. Same energy for ssd and csd, fullscreen and no-fullscreen, tearing and no-tearing rules.

If multiple rules in a list match a given view, the most specific rule wins. Like, watch:

    app-id  title  action
    foo     bar    ssd
    foo     *      csd
    *       bar    csd
    *       baz    ssd

A view with app-id 'foo' and title 'bar' would get ssd despite matching two csd rules, because the first rule is most specific 🔥. And a view with app-id 'foo' and title 'baz' would get csd despite matching the last rule in the list — because app-id specificity takes priority over title specificity. iykyk 💅

If a view isn't matched by any rule, river will respect the csd/ssd wishes of the client, and may start the view floating based on simple heuristics intended to catch popup-like views 🪟✨

Heads up bestie: if a view is started fullscreen or is not floating, then position and dimensions rules will have no effect. A view must be matched by a float rule in order for them to take effect. No cap.
  • rule-del [-app-id glob|-title glob] action — deletes a rule that was created using rule-add with the given arguments. Gone. Poof. Blocked. 🚫
  • list-rules float|ssd|tags|position|dimensions|fullscreen — prints out the specified rule list 📋. The output is ordered from most specific to least specific — literally the same order in which views are checked against when searching for a match. Only the first matching rule in the list has an effect on a given view.

🌸 CONFIGURATION 🌸

  • default-attach-mode top|bottom|above|below|after <N> — sets the attach mode that all outputs use by default.

Possible values, bestie:

  • top — prepends the newly spawned view at the top of the stack.
  • bottom — appends the newly spawned view at the bottom of the stack.
  • above — inserts the newly spawned view above the currently focused view.
  • below — inserts the newly spawned view below the currently focused view.
  • after <N> — inserts the newly spawned view after N views in the stack.
Ngl, the deprecated attach-mode command is aliased to default-attach-mode for backwards compatibility. Old news but it still slays 🫶
  • output-attach-mode top|bottom|above|below|after <N> — sets the attach mode of the currently focused output, overriding the value of default-attach-mode if there is one.
  • allow-tearing enabled|disabled — allows fullscreen views to tear if the view requests it. See also the tearing rule to force-enable tearing for specific views.
  • background-color 0xRRGGBB|0xRRGGBBAA — sets the background color 🎨
  • border-color-focused 0xRRGGBB|0xRRGGBBAA — sets the border color of focused views.
  • border-color-unfocused 0xRRGGBB|0xRRGGBBAA — sets the border color of unfocused views.
  • border-color-urgent 0xRRGGBB|0xRRGGBBAA — sets the border color of urgent views 🚨
  • border-width pixels — sets the border width to pixels.
  • focus-follows-cursor disabled|normal|always — there are three available modes:
    • disabled — moving the cursor does not affect focus. This is the default.
    • normal — moving the cursor over a view will focus that view. Moving the cursor within a view will not re-focus that view if focus has moved elsewhere.
    • always — moving the cursor will always focus whatever view is under the cursor.

If the view to be focused is on an output that doesn't have focus, focus is switched to that output. Cursor main character energy, fr fr 🖱️👑

  • hide-cursor timeout timeout — hides the cursor if it wasn't moved in the last timeout milliseconds, until it's moved again. The default value is 0, which disables automatically hiding the cursor. The cursor shows up again on any movement ✨
  • hide-cursor when-typing enabled|disabled — hides the cursor when pressing any non-modifier key. Shows it again on any movement.
  • set-cursor-warp disabled|on-output-change|on-focus-change — sets the cursor warp mode. The page says there are two available modes and then lists three — we love a little plot twist 💀 anyway:
    • disabled — the cursor will not be warped. This is the default.
    • on-output-change — when a different output is focused, the cursor will be warped to its center.
    • on-focus-change — when a different view/output is focused, the cursor will be warped to its center.
  • set-repeat rate delay — sets the keyboard repeat rate to rate key repeats per second and the repeat delay to delay milliseconds. The default is a rate of 25 repeats per second and a delay of 600ms. Typing go brrr ⌨️🔥
  • xcursor-theme theme_name [size] — sets the xcursor theme to theme_name and optionally sets the size. The theme of the default seat determines the default for Xwayland and is made available through the XCURSOR_THEME and XCURSOR_SIZE environment variables 🎀

💜 INPUT CONFIGURATION 💜

  • list-inputs — lists all input devices.
  • list-input-configs — lists all input configurations.
  • keyboard-layout [-rules rules] [-model model] [-variant variant] [-options options] layout — sets the XKB layout for all keyboards. Defaults from libxkbcommon are used for everything left unspecified. Note that layout may be a comma separated list of layouts (e.g. "us,de") which may be switched between using various key combinations configured through the options argument (e.g. -options "grp:ctrl_space_toggle"). See xkeyboard-config(7) for possible values and more info 🧚
  • keyboard-layout-file path — sets the XKB layout for all keyboards from an XKB keymap file at the provided path. Documentation for the XKB keymap file format can be found at the following URL: https://xkbcommon.org/doc/current/keymap-text-format-v1.html

So the input command is what you use to create a configuration rule for an input device identified by its name. The name of an input device consists of its type, its decimal vendor id, its decimal product id and finally its self-advertised name, separated by -. Simple globbing patterns are supported — see the rules section for more on globs 🦋

A list of all the device properties you can configure is below 👇 but bestie, note that not every input device supports every property.

  • input name events enabled|disabled|disabled-on-external-mouse — configures whether the input device's events will be used by river.
  • input name accel-profile none|flat|adaptive — sets the pointer acceleration profile of the input device.
  • input name pointer-accel factor — sets the pointer acceleration factor of the input device. Needs a float between -1.0 and 1.0.
  • input name click-method none|button-areas|clickfinger — sets the click method of the input device.
  • input name drag enabled|disabled — enables or disables the tap-and-drag functionality of the input device.
  • input name drag-lock enabled|disabled — enables or disables the drag lock functionality of the input device 🔒
  • input name disable-while-typing enabled|disabled — enables or disables the disable-while-typing functionality of the input device.
  • input name disable-while-trackpointing enabled|disabled — enables or disables the disable-while-trackpointing functionality of the input device.
  • input name middle-emulation enabled|disabled — enables or disables the middle click emulation functionality of the input device.
  • input name natural-scroll enabled|disabled — enables or disables the natural scroll functionality of the input device. If active, the scroll direction is inverted 🌀
  • input name scroll-factor factor — sets the scroll factor of the input device. Accepts a postive value greater than 0. For example, a factor of 0.5 will make scrolling twice as slow while a factor of 3 will make scrolling 3 times as fast.
  • input name left-handed enabled|disabled — enables or disables the left handed mode of the input device.
  • input name tap enabled|disabled — enables or disables the tap functionality of the input device 👆
  • input name tap-button-map left-right-middle|left-middle-right — configures the button mapping for tapping.
    • left-right-middle — 1 finger tap equals left click, 2 finger tap equals right click, 3 finger tap equals middle click.
    • left-middle-right — 1 finger tap equals left click, 2 finger tap equals middle click, 3 finger tap equals right click.
  • input name scroll-method none|two-finger|edge|button — sets the scroll method of the input device.
  • none — no scrolling, zero, nada, the pointer just vibes 🌸
    • two-finger — scroll by swiping with two fingers at the same time ✨ (yes, both. together. slay)
    • edge — scroll by swiping along the edge, very demure, very mindful 🎀
    • button — scroll with pointer movement while you hold a button down 🖱️
  • input name scroll-button button — sets the scroll button of an input device. button is the name of a Linux input event code, so type it exactly, bestie, no improvising 💅
  • input name scroll-button-lock enabled|disabled — turns the scroll button lock functionality of the input device on or off. When it's active, you don't have to keep the button held down — like, one press and the button is considered held down, and a second press releases it. Two taps and you're free, it's giving toggle 😌
  • input name map-to-output output|disabled — maps the input to a given output. And the cute part? This is valid even if the output isn't currently active — it'll just lead to the device being mapped once it's connected. Future-proofing, we love to see it 🔥

🌈 EXAMPLES 🌈

Bind Super+Return in normal mode to spawn a foot(1) terminal — the classic, the icon, the main character move:

riverctl map normal Mod4 Return spawn 'foot --app-id=foobar'

Bind Super+Shift+J to swap the focused view with the next visible view:

riverctl map normal Mod4+Shift J swap next

👑 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>.

🦋 SEE ALSO 🦋

river(1), rivertile(1)

k that's the whole page, bestie — go forth and configure 💖 This one's from the 2026-09-11 edition of RIVERCTL(1), and no cap, you just read all of it. Periodt. 💅✨

📦 where this page comes from