1RIVERCTL(1) General Commands Manual RIVERCTL(1)
2
6 riverctl - command-line interface for controlling river
7
9 riverctl [options] command [command specific arguments]
10
12 riverctl is a command-line utility used to control and configure river
13 over the Wayland protocol.
14
16 -h
17 Print a help message and exit.
18 -version
20 Print the version number and exit.
21
23 ACTIONS
24 close
25 Close the focused view.
26 csd-filter-add app-id|title pattern
28 Add pattern to the CSD filter list. Views with this pattern are
29 told to use client side decoration instead of the default server
30 side decoration. Note that this affects new views as well as al‐
31 ready existing ones. Title updates are not taken into account.
32 csd-filter-remove app-id|title pattern
34 Remove pattern from the CSD filter list. Note that this affects new
35 views as well as already existing ones.
36 exit
38 Exit the compositor, terminating the Wayland session.
39 float-filter-add app-id|title pattern
41 Add a pattern to the float filter list. Note that this affects only
42 new views, not already existing ones. Title updates are also not
43 taken into account.
44 float-filter-remove app-id|title pattern
46 Remove an app-id or title from the float filter list. Note that
47 this affects only new views, not already existing ones.
48 focus-output next|previous|up|right|down|left|name
50 Focus the next or previous output, the closest output in any direc‐
51 tion or an output by name.
52 focus-view next|previous
54 Focus the next or previous view in the stack.
55 move up|down|left|right delta
57 Move the focused view in the specified direction by delta logical
58 pixels. The view will be set to floating.
59 resize horizontal|vertical delta
61 Resize the focused view along the given axis by delta logical pix‐
62 els. The view will be set to floating.
63 snap up|down|left|right
65 Snap the focused view to the specified screen edge. The view will
66 be set to floating.
67 send-to-output next|previous|up|right|down|left|name
69 Send the focused view to the next or previous output, the closest
70 output in any direction or to an output by name.
71 spawn shell_command
73 Run shell_command using `/bin/sh -c shell_command`. Note that spawn
74 only takes a single argument. To spawn a command taking multiple
75 arguments, wrapping the command in quotes is recommended.
76 swap next|previous
78 Swap the focused view with the next/previous visible non-floating
79 view. If the first/last view in the stack is focused, wrap.
80 toggle-float
82 Toggle the floating state of the focused view.
83 toggle-fullscreen
85 Toggle the fullscreen state of the focused view.
86 zoom
88 Bump the focused view to the top of the layout stack. If the top
89 view in the stack is already focused, bump the second view.
90 default-layout namespace
92 Set the layout namespace to be used by all outputs by default.
93 output-layout namespace
95 Set the layout namespace of currently focused output, overriding
96 the value set with default-layout if any.
97 send-layout-cmd namespace command
99 Send command to the layout generator on the currently focused out‐
100 put with the given namespace, if any. What commands a layout gener‐
101 ator understands depends on the layout generator. For rivertile,
102 see the documentation in the rivertile(1) man page.
103 TAG MANAGEMENT
105 Tags are similar to workspaces but more flexible. You can assign views
106 multiple tags and focus multiple tags simultaneously. Bitfields are
107 used to describe sets of tags when interfacing with river. As such, the
108 following commands take a normal base 10 number as their argument but
109 the semantics are best understood in binary. The binary number
110 000000001 represents a set containing only tag 1 while 100001101 repre‐
111 sents a set containing tags 1, 3, 4, and 9.
112 When a view spawns it is assigned the currently focused tags of the
114 output.
115 At least one tag must always be focused and each view must be assigned
117 at least one tag. Operations that would violate either of these re‐
118 quirements are ignored by river.
119 set-focused-tags tags
121 Show views with tags corresponding to the set bits of tags on the
122 currently focused output.
123 set-view-tags tags
125 Assign the currently focused view the tags corresponding to the set
126 bits of tags.
127 toggle-focused-tags tags
129 Toggle visibility of views with tags corresponding to the set bits
130 of tags on the currently focused output.
131 toggle-view-tags tags
133 Toggle the tags of the currently focused view corresponding to the
134 set bits of tags.
135 spawn-tagmask tagmask
137 Set a tagmask to filter the tags assigned to newly spawned views.
138 This mask will be applied to the tags of new views with a bitwise
139 and. If, for example, the tags 000011111 are focused and the spawn
140 tagmask is 111110001, a new view will be assigned the tags
141 000010001. If no tags would remain after filtering, the tagmask is
142 ignored.
143 focus-previous-tags
145 Sets tags to their previous value on the currently focused output,
146 allowing jumping back and forth between 2 tag setups.
147 send-to-previous-tags
149 Assign the currently focused view the previous tags of the cur‐
150 rently focused output.
151 MAPPINGS
153 Mappings are modal in river. Each mapping is associated with a mode and
154 is only active while in that mode. There are two special modes: "nor‐
155 mal" and "locked". The normal mode is the initial mode on startup. The
156 locked mode is automatically entered while the session is locked (e.g.
157 due to a screenlocker). It cannot be entered or exited manually.
158 The following modifiers are available for use in mappings:
160 • Shift
162 • Lock
163 • Control
164 • Mod1 (Alt)
165 • Mod2
166 • Mod3
167 • Mod4 (Super)
168 • Mod5
169 • None
170 Alt and Super are aliases for Mod1 and Mod4 respectively. None allows
173 creating a mapping without modifiers
174 Keys are specified by their XKB keysym name. See /usr/include/xkbcom‐
176 mon/xkbcommon-keysyms.h for the complete list.
177 Mouse buttons are specified by linux input event code names. The most
179 commonly used values are:
180 • BTN_LEFT - left mouse button
182 • BTN_RIGHT - right mouse button
183 • BTN_MIDDLE - middle mouse button
184 A complete list may be found in /usr/include/linux/input-event-codes.h
187 declare-mode name
189 Create a new mode called name.
190 enter-mode name
192 Switch to given mode if it exists.
193 map [-release|-repeat|-layout index] mode modifiers key command
195 Run command when key is pressed while modifiers are held down and
196 in the specified mode.
197 • -release: if passed activate on key release instead of key
199 press
200 • -repeat: if passed activate repeatedly until key release; may
201 not be used with -release
202 • -layout: if passed, a specific layout is pinned to the mapping.
203 When the mapping is checked against a pressed key, this layout
204 is used to translate the key independent of the active layout
205 • index: zero-based index of a layout set with the keyboard-
206 layout command. If the index is out of range, the -layout
207 option will have no effect
208 • mode: name of the mode for which to create the mapping
209 • modifiers: one or more of the modifiers listed above, separated
210 by a plus sign (+).
211 • key: an XKB keysym name as described above
212 • command: any command that may be run with riverctl
213 map-pointer mode modifiers button action|command
216 Move or resize views or run command when button and modifiers are
217 held down while in the specified mode. The view under the cursor
218 will be focused.
219 • mode: name of the mode for which to create the mapping
221 • modifiers: one or more of the modifiers listed above, separated
222 by a plus sign (+).
223 • button: the name of a linux input event code as described above
224 • action: one of the following values:
225 • move-view
226 • resize-view
227 • command: any command that may be run with riverctl
228 map-switch mode lid|tablet state command
231 Run command when river receives a certain switch event.
232 • mode: name of the mode for which to create the mapping
234 • lid|tablet: 'lid switch' and 'tablet mode switch' are supported
235 • state:
236 • possible states for lid:
237 • close
238 • open
239 • possible states for tablet:
240 • on
241 • off
242 • command: any command that may be run with riverctl
243 unmap [-release] mode modifiers key
246 Remove the mapping defined by the arguments:
247 • -release: if passed unmap the key release instead of the key
249 press
250 • mode: name of the mode for which to remove the mapping
251 • modifiers: one or more of the modifiers listed above, separated
252 by a plus sign (+).
253 • key: an XKB keysym name as described above
254 unmap-pointer mode modifiers button
257 Remove the pointer mapping defined by the arguments:
258 • mode: name of the mode for which to remove the mapping
260 • modifiers: one or more of the modifiers listed above, separated
261 by a plus sign (+).
262 • button: the name of a linux input event code as described above
263 unmap-switch mode lid|tablet state
266 Remove the switch mapping defined by the arguments:
267 • mode: name of the mode for which to remove the mapping
269 • lid|tablet: the switch for which to remove the mapping
270 • state: a state as listed above
271 CONFIGURATION
274 attach-mode top|bottom
275 Configure where new views should attach to the view stack.
276 background-color 0xRRGGBB|0xRRGGBBAA
278 Set the background color.
279 border-color-focused 0xRRGGBB|0xRRGGBBAA
281 Set the border color of focused views.
282 border-color-unfocused 0xRRGGBB|0xRRGGBBAA
284 Set the border color of unfocused views.
285 border-color-urgent 0xRRGGBB|0xRRGGBBAA
287 Set the border color of urgent views.
288 border-width pixels
290 Set the border width to pixels.
291 focus-follows-cursor disabled|normal|always
293 There are three available modes:
294 • disabled: Moving the cursor does not affect focus. This is the
296 default.
297 • normal: Moving the cursor over a view will focus that view.
298 Moving the cursor within a view will not re-focus that view if
299 focus has moved elsewhere.
300 • always: Moving the cursor will always focus whatever view is
301 under the cursor.
302 If the view to be focused is on an output that does not have focus,
305 focus is switched to that output.
306 hide-cursor timeout timeout
308 Hide the cursor if it wasn't moved in the last timeout milliseconds
309 until it is moved again. The default value is 0, which disables au‐
310 tomatically hiding the cursor. Show the cursor again on any move‐
311 ment.
312 hide-cursor when-typing enabled|disabled
314 Hide the cursor when pressing any non-modifier key. Show the cursor
315 again on any movement.
316 set-cursor-warp disabled|on-output-change|on-focus-change
318 Set the cursor warp mode. There are two available modes:
319 • disabled: Cursor will not be warped. This is the default.
321 • on-output-change: When a different output is focused, the cur‐
322 sor will be warped to its center.
323 • on-focus-change: When a different view/output is focused, the
324 cursor will be warped to its center.
325 set-repeat rate delay
328 Set the keyboard repeat rate to rate key repeats per second and re‐
329 peat delay to delay milliseconds.
330 xcursor-theme theme_name [size]
332 Set the xcursor theme to theme_name and optionally set the size.
333 The theme of the default seat determines the default for Xwayland
334 and is made available through the XCURSOR_THEME and XCURSOR_SIZE
335 environment variables.
336 INPUT CONFIGURATION
338 list-inputs
339 List all input devices.
340 list-input-configs
342 List all input configurations.
343 keyboard-layout [-rules rules] [-model model] [-variant variant] [-op‐
345 tions options] layout
346 Set the XKB layout for all keyboards. Defaults from libxkbcommon
347 are used for everything left unspecified. Note that layout may be a
348 comma separated list of layouts (e.g. "us,de") which may be
349 switched between using various key combinations configured through
350 the options argument (e.g. -options "grp:ctrl_space_toggle"). See
351 xkeyboard-config(7) for possible values and more information.
352 keyboard-group-create group_name
354 Create a keyboard group. A keyboard group collects multiple key‐
355 boards in a single logical keyboard. This means that all state,
356 like the active modifiers, is shared between the keyboards in a
357 group.
358 keyboard-group-destroy group_name
360 Destroy the keyboard group with the given name. All attached key‐
361 boards will be released, making them act as seperate devices again.
362 keyboard-group-add group_name input_device_name
364 Add a keyboard to a keyboard group, identified by the keyboard's
365 input device name. Any currently connected and future keyboards
366 with the given name will be added to the group.
367 keyboard-group-remove group_name input_device_name
369 Remove a keyboard from a keyboard group, identified by the key‐
370 board's input device name.
371 The input command can be used to create a configuration rule for an in‐
373 put device identified by its name. The name of an input device consists
374 of its type, its numerical vendor id, its numerical product id and fi‐
375 nally its self-advertised name, separated by -.
376 A list of all device properties that can be configured may be found be‐
378 low. However note that not every input device supports every property.
379 input name events enabled|disabled|disabled-on-external-mouse
381 Configure whether the input devices events will be used by river.
382 input name accel-profile none|flat|adaptive
384 Set the pointer acceleration profile of the input device.
385 input name pointer-accel factor
387 Set the pointer acceleration factor of the input device. Needs a
388 float between -1.0 and 1.0.
389 input name click-method none|button-areas|clickfinger
391 Set the click method of the input device.
392 input name drag enabled|disabled
394 Enable or disable the tap-and-drag functionality of the input de‐
395 vice.
396 input name drag-lock enabled|disabled
398 Enable or disable the drag lock functionality of the input device.
399 input name disable-while-typing enabled|disabled
401 Enable or disable the disable-while-typing functionality of the in‐
402 put device.
403 input name middle-emulation enabled|disabled
405 Enable or disable the middle click emulation functionality of the
406 input device.
407 input name natural-scroll enabled|disabled
409 Enable or disable the natural scroll functionality of the input de‐
410 vice. If active, the scroll direction is inverted.
411 input name left-handed enabled|disabled
413 Enable or disable the left handed mode of the input device.
414 input name tap enabled|disabled
416 Enable or disable the tap functionality of the input device.
417 input name tap-button-map left-right-middle|left-middle-right
419 Configure the button mapping for tapping.
420 • left-right-middle: 1 finger tap equals left click, 2 finger tap
422 equals right click, 3 finger tap equals middle click.
423 • left-middle-right: 1 finger tap equals left click, 2 finger tap
424 equals middle click, 3 finger tap equals right click.
425 input name scroll-method none|two-finger|edge|button
428 Set the scroll method of the input device.
429 • none: No scrolling
431 • two-finger: Scroll by swiping with two fingers simultaneously
432 • edge: Scroll by swiping along the edge
433 • button: Scroll with pointer movement while holding down a but‐
434 ton
435 input name scroll-button button
438 Set the scroll button of an input device. button is the name of a
439 linux input event code.
440
442 Bind Super+Return in normal mode to spawn a foot(1) terminal:
443 riverctl map normal Mod4 Return spawn 'foot --app-id=foobar'
445 Bind Super+Shift+J to swap the focused view with the next visible view:
447 riverctl map normal Mod4+Shift J swap next
449
451 Maintained by Isaac Freund <mail@isaacfreund.com> who is assisted by
452 open source contributors. For more information about river's develop‐
453 ment, see <https://github.com/riverwm/river>.
454
456 river(1), rivertile(1)
457github.com/riverwm/river 2023-07-21 RIVERCTL(1)