1RIVERCTL(1)                 General Commands Manual                RIVERCTL(1)
2
3
4

NAME

6       riverctl - command-line interface for controlling river
7

SYNOPSIS

9       riverctl [options] command [command specific arguments]
10

DESCRIPTION

12       riverctl is a command-line utility used to control and configure river
13       over the Wayland protocol.
14

OPTIONS

16       -h
17           Print a help message and exit.
18
19       -version
20           Print the version number and exit.
21

COMMANDS

23   ACTIONS
24       close
25           Close the focused view.
26
27       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
33       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
37       exit
38           Exit the compositor, terminating the Wayland session.
39
40       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
45       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
49       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
53       focus-view next|previous
54           Focus the next or previous view in the stack.
55
56       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
60       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
64       snap up|down|left|right
65           Snap the focused view to the specified screen edge. The view will
66           be set to floating.
67
68       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
72       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
77       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
81       toggle-float
82           Toggle the floating state of the focused view.
83
84       toggle-fullscreen
85           Toggle the fullscreen state of the focused view.
86
87       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
91       default-layout namespace
92           Set the layout namespace to be used by all outputs by default.
93
94       output-layout namespace
95           Set the layout namespace of currently focused output, overriding
96           the value set with default-layout if any.
97
98       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
104   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
113       When a view spawns it is assigned the currently focused tags of the
114       output.
115
116       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
120       set-focused-tags tags
121           Show views with tags corresponding to the set bits of tags on the
122           currently focused output.
123
124       set-view-tags tags
125           Assign the currently focused view the tags corresponding to the set
126           bits of tags.
127
128       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
132       toggle-view-tags tags
133           Toggle the tags of the currently focused view corresponding to the
134           set bits of tags.
135
136       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
144       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
148       send-to-previous-tags
149           Assign the currently focused view the previous tags of the cur‐
150           rently focused output.
151
152   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
159       The following modifiers are available for use in mappings:
160
161           •   Shift
162           •   Lock
163           •   Control
164           •   Mod1 (Alt)
165           •   Mod2
166           •   Mod3
167           •   Mod4 (Super)
168           •   Mod5
169           •   None
170
171
172       Alt and Super are aliases for Mod1 and Mod4 respectively. None allows
173       creating a mapping without modifiers
174
175       Keys are specified by their XKB keysym name. See /usr/include/xkbcom‐
176       mon/xkbcommon-keysyms.h for the complete list.
177
178       Mouse buttons are specified by linux input event code names. The most
179       commonly used values are:
180
181           •   BTN_LEFT - left mouse button
182           •   BTN_RIGHT - right mouse button
183           •   BTN_MIDDLE - middle mouse button
184
185
186       A complete list may be found in /usr/include/linux/input-event-codes.h
187
188       declare-mode name
189           Create a new mode called name.
190
191       enter-mode name
192           Switch to given mode if it exists.
193
194       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
198-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
205index: 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
208mode: name of the mode for which to create the mapping
209modifiers: one or more of the modifiers listed above, separated
210               by a plus sign (+).
211key: an XKB keysym name as described above
212command: any command that may be run with riverctl
213
214
215       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
220mode: name of the mode for which to create the mapping
221modifiers: one or more of the modifiers listed above, separated
222               by a plus sign (+).
223button: the name of a linux input event code as described above
224action: one of the following values:
225               •   move-view
226               •   resize-view
227command: any command that may be run with riverctl
228
229
230       map-switch mode lid|tablet state command
231           Run command when river receives a certain switch event.
232
233mode: name of the mode for which to create the mapping
234lid|tablet: 'lid switch' and 'tablet mode switch' are supported
235state:
236               •   possible states for lid:
237                   •   close
238                   •   open
239               •   possible states for tablet:
240                   •   on
241                   •   off
242command: any command that may be run with riverctl
243
244
245       unmap [-release] mode modifiers key
246           Remove the mapping defined by the arguments:
247
248-release: if passed unmap the key release instead of the key
249               press
250mode: name of the mode for which to remove the mapping
251modifiers: one or more of the modifiers listed above, separated
252               by a plus sign (+).
253key: an XKB keysym name as described above
254
255
256       unmap-pointer mode modifiers button
257           Remove the pointer mapping defined by the arguments:
258
259mode: name of the mode for which to remove the mapping
260modifiers: one or more of the modifiers listed above, separated
261               by a plus sign (+).
262button: the name of a linux input event code as described above
263
264
265       unmap-switch mode lid|tablet state
266           Remove the switch mapping defined by the arguments:
267
268mode: name of the mode for which to remove the mapping
269lid|tablet: the switch for which to remove the mapping
270state: a state as listed above
271
272
273   CONFIGURATION
274       attach-mode top|bottom
275           Configure where new views should attach to the view stack.
276
277       background-color 0xRRGGBB|0xRRGGBBAA
278           Set the background color.
279
280       border-color-focused 0xRRGGBB|0xRRGGBBAA
281           Set the border color of focused views.
282
283       border-color-unfocused 0xRRGGBB|0xRRGGBBAA
284           Set the border color of unfocused views.
285
286       border-color-urgent 0xRRGGBB|0xRRGGBBAA
287           Set the border color of urgent views.
288
289       border-width pixels
290           Set the border width to pixels.
291
292       focus-follows-cursor disabled|normal|always
293           There are three available modes:
294
295disabled: Moving the cursor does not affect focus. This is the
296               default.
297normal: 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.
300always: Moving the cursor will always focus whatever view is
301               under the cursor.
302
303
304           If the view to be focused is on an output that does not have focus,
305           focus is switched to that output.
306
307       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
313       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
317       set-cursor-warp disabled|on-output-change|on-focus-change
318           Set the cursor warp mode. There are two available modes:
319
320disabled: Cursor will not be warped. This is the default.
321on-output-change: When a different output is focused, the cur‐
322               sor will be warped to its center.
323on-focus-change: When a different view/output is focused, the
324               cursor will be warped to its center.
325
326
327       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
331       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
337   INPUT CONFIGURATION
338       list-inputs
339           List all input devices.
340
341       list-input-configs
342           List all input configurations.
343
344       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
353       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
359       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
363       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
368       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
372       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
377       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
380       input name events enabled|disabled|disabled-on-external-mouse
381           Configure whether the input devices events will be used by river.
382
383       input name accel-profile none|flat|adaptive
384           Set the pointer acceleration profile of the input device.
385
386       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
390       input name click-method none|button-areas|clickfinger
391           Set the click method of the input device.
392
393       input name drag enabled|disabled
394           Enable or disable the tap-and-drag functionality of the input de‐
395           vice.
396
397       input name drag-lock enabled|disabled
398           Enable or disable the drag lock functionality of the input device.
399
400       input name disable-while-typing enabled|disabled
401           Enable or disable the disable-while-typing functionality of the in‐
402           put device.
403
404       input name middle-emulation enabled|disabled
405           Enable or disable the middle click emulation functionality of the
406           input device.
407
408       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
412       input name left-handed enabled|disabled
413           Enable or disable the left handed mode of the input device.
414
415       input name tap enabled|disabled
416           Enable or disable the tap functionality of the input device.
417
418       input name tap-button-map left-right-middle|left-middle-right
419           Configure the button mapping for tapping.
420
421left-right-middle: 1 finger tap equals left click, 2 finger tap
422               equals right click, 3 finger tap equals middle click.
423left-middle-right: 1 finger tap equals left click, 2 finger tap
424               equals middle click, 3 finger tap equals right click.
425
426
427       input name scroll-method none|two-finger|edge|button
428           Set the scroll method of the input device.
429
430none: No scrolling
431two-finger: Scroll by swiping with two fingers simultaneously
432edge: Scroll by swiping along the edge
433button: Scroll with pointer movement while holding down a but‐
434               ton
435
436
437       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

EXAMPLES

442       Bind Super+Return in normal mode to spawn a foot(1) terminal:
443
444           riverctl map normal Mod4 Return spawn 'foot --app-id=foobar'
445
446       Bind Super+Shift+J to swap the focused view with the next visible view:
447
448           riverctl map normal Mod4+Shift J swap next
449

AUTHORS

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

SEE ALSO

456       river(1), rivertile(1)
457
458
459
460github.com/riverwm/river          2023-01-20                       RIVERCTL(1)
Impressum