riverctl - Man Page

close

Close the focused view.

exit

Exit the compositor, terminating the Wayland session.

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.

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.

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.

resize horizontal|vertical delta

Resize the focused view along the given axis by delta logical pixels. The view will be set to floating.

snap up|down|left|right

Snap the focused view to the specified screen edge. The view will be set to floating.

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.

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.

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.

toggle-float

Toggle the floating state of the focused view.

toggle-fullscreen

Toggle the fullscreen state of the focused view.

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.

default-layout namespace

Set the layout namespace to be used by all outputs by default.

output-layout namespace

Set the layout namespace of currently focused output, overriding the value set with default-layout if any.

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.

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.

When a view spawns it is assigned the currently focused tags of the output.

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.

set-focused-tags tags

Show views with tags corresponding to the set bits of tags on the currently focused output.

set-view-tags tags

Assign the currently focused view the tags corresponding to the set bits of tags.

toggle-focused-tags tags

Toggle visibility of views with tags corresponding to the set bits of tags on the currently focused output.

toggle-view-tags tags

Toggle the tags of the currently focused view corresponding to the set bits of tags.

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.

focus-previous-tags

Sets tags to their previous value on the currently focused output, allowing jumping back and forth between 2 tag setups.

send-to-previous-tags

Assign the currently focused view the previous tags of the currently focused output.

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.

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.

Keys are specified by their XKB keysym name. See /usr/include/xkbcommon/xkbcommon-keysyms.h for the complete list.

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

declare-mode name

Create a new mode called name.

enter-mode name

Switch to given mode 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 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.

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.

rule-add [-app-id glob|-title glob] action [arguments]

  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 as the first rule is most specific. Furthermore a view with app-id 'foo' and title 'baz' would get csd despite matching the last rule in the list since app-id specificity takes priority over title specificity.

If a view is not 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.

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.

rule-del [-app-id glob|-title glob] action

list-rules float|ssd|tags|position|dimensions|fullscreen

default-attach-mode top|bottom|above|below|after <N>

Set the attach mode to be used by all outputs by default.

Possible values:

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

Note that the deprecated attach-mode command is aliased to default-attach-mode for backwards compatibility.

output-attach-mode top|bottom|above|below|after <N>

Set the attach mode of the currently focused output, overriding the value of default-attach-mode if any.

background-color 0xRRGGBB|0xRRGGBBAA

Set the background color.

border-color-focused 0xRRGGBB|0xRRGGBBAA

Set the border color of focused views.

border-color-unfocused 0xRRGGBB|0xRRGGBBAA

Set the border color of unfocused views.

border-color-urgent 0xRRGGBB|0xRRGGBBAA

Set the border color of urgent views.

border-width pixels

Set 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 does not have focus, focus is switched to that output.

hide-cursor timeout timeout

Hide the cursor if it wasn't moved in the last timeout milliseconds until it is moved again. The default value is 0, which disables automatically hiding the cursor. Show the cursor again on any movement.

hide-cursor when-typing enabled|disabled

Hide the cursor when pressing any non-modifier key. Show the cursor again on any movement.

set-cursor-warp disabled|on-output-change|on-focus-change

Set the cursor warp mode. There are two available modes:

• disabled: 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

Set the keyboard repeat rate to rate key repeats per second and repeat delay to delay milliseconds.

xcursor-theme theme_name [size]

Set the xcursor theme to theme_name and optionally set 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.

list-inputs

List all input devices.

list-input-configs

List all input configurations.

keyboard-layout [-rules rules] [-model model] [-variant variant]  [-options options] layout

Set 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 information.

keyboard-layout-file path

Set 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

keyboard-group-create group_name

Create a keyboard group. A keyboard group collects multiple keyboards in a single logical keyboard. This means that all state, like the active modifiers, is shared between the keyboards in a group.

keyboard-group-destroy group_name

Destroy the keyboard group with the given name. All attached keyboards will be released, making them act as separate devices again.

keyboard-group-add group_name input_device_name

Add a keyboard to a keyboard group, identified by the keyboard's input device name. Any currently connected and future keyboards with the given name will be added to the group. Simple globbing patterns are supported, see the rules section for further information on globs.

keyboard-group-remove group_name input_device_name

Remove a keyboard from a keyboard group, identified by the keyboard's input device name.

The input command can be used to create a configuration rule for an input device identified by its name. The name of an input device consists of its type, its numerical vendor id, its numerical product id and finally its self-advertised name, separated by -. Simple globbing patterns are supported, see the rules section for further information on globs.

A list of all device properties that can be configured may be found below. However note that not every input device supports every property.

input name events enabled|disabled|disabled-on-external-mouse

Configure whether the input devices events will be used by river.

input name accel-profile none|flat|adaptive

Set the pointer acceleration profile of the input device.

input name pointer-accel factor

Set 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

Set the click method of the input device.

input name drag enabled|disabled

Enable or disable the tap-and-drag functionality of the input device.

input name drag-lock enabled|disabled

Enable or disable the drag lock functionality of the input device.

input name disable-while-typing enabled|disabled

Enable or disable the disable-while-typing functionality of the input device.

input name disable-while-trackpointing enabled|disabled

Enable or disable the disable-while-trackpointing functionality of the input device.

input name middle-emulation enabled|disabled

Enable or disable the middle click emulation functionality of the input device.

input name natural-scroll enabled|disabled

Enable or disable the natural scroll functionality of the input device. If active, the scroll direction is inverted.

input name scroll-factor factor

Set 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

Enable or disable the left handed mode of the input device.

input name tap enabled|disabled

Enable or disable the tap functionality of the input device.

input name tap-button-map left-right-middle|left-middle-right

Configure 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

Set the scroll method of the input device.

• none: No scrolling
• two-finger: Scroll by swiping with two fingers simultaneously
• edge: Scroll by swiping along the edge
• button: Scroll with pointer movement while holding down a button

input name scroll-button button

Set the scroll button of an input device. button is the name of a Linux input event code.

input name map-to-output output|disabled

Maps the input to a given output. This is valid even if the output isn't currently active and will lead to the device being mapped once it is connected.