1HERBSTLUFTWM(1)                                                HERBSTLUFTWM(1)
2
3
4

NAME

6       herbstluftwm - a manual tiling window manager for X
7

SYNOPSIS

9       herbstluftwm [OPTION ...]
10

DESCRIPTION

12       Starts the herbstluftwm window manager on DISPLAY. It also listens for
13       calls from herbstclient(1) and executes them. The list of available
14       COMMANDS is listed below.
15
16       OPTION can be:
17
18       -v, --version
19           print version and exit
20
21       -h, --help
22           print a short help and exit
23
24       -c, --autostart PATH
25           use PATH as autostart file instead of the one in $XDG_CONFIG_HOME
26
27       -l, --locked
28           Initially set the monitors_locked setting to 1
29
30       --exit-on-xerror
31           Make herbstluftwm exit whenever xlib reports an error. This may
32           only be activated for automated testing and never for actual
33           sessions.
34
35       --no-tag-import
36           Do not preserve the tags (virtual desktops) from a previous running
37           window manager.
38
39       --verbose
40           print verbose information to stderr. This can be switched at
41           run-time by the verbose setting.
42
43       This manual documents the scripting and configuration interface. For a
44       more verbose introduction see herbstluftwm-tutorial(7).
45

TILING ALGORITHM

47       The basic tiling concept is that the layout is represented by a binary
48       tree. On startup you see one big frame across the entire screen. A
49       frame fulfills exactly one of the following conditions:
50
51        1. Frame contains windows:
52
53           It shows some clients and arranges them. The current layout
54           algorithms are:
55
56           ·   0: vertical - clients are placed below each other
57
58           ·   1: horizontal - clients are placed next to each other
59
60           ·   2: max - all clients are maximized in this frame
61
62           ·   3: grid - clients are arranged in an almost quadratic grid
63
64        2. Frame is split into subframes:
65
66           It is split into exactly two subframes in a configurable fraction
67           either in a vertical or horizontal way. So it produces two frames
68           which fulfill the same conditions (new frames always are about to
69           contain windows). If you split a frame that already contains
70           windows, the windows are inherited by the first new child frame.
71
72       If a new window appears, it is put in the currently focused frame. Only
73       the leaves of the frame tree can be focused.
74
75       A frame can be removed, it is then merged with its neighbour frame. Due
76       to the layout structure of a binary tree, each frame (i.e. node in
77       binary tree) has exactly one neighbour.
78
79       The analogy to a binary tree is explained the best way with a small
80       example: On startup you have a simple binary tree, with one frame that
81       can contain clients:
82
83           C
84
85       When splitting it (e.g. with the command split vertical 0.5) you will
86       get this:
87
88             V
89            / \
90           C   C
91
92       You also can split the left frame horizontally and you will get:
93
94               V
95              / \
96             H   C
97            / \
98           C   C
99
100       If you change the focus to the client on the right and remove this
101       frame, it will be merged with the left subtree and you will get:
102
103             H
104            / \
105           C   C
106
107       The layout command prints the current layout of all tags as a tree.
108

FRAME INDEX

110       The exact position of a frame in the layout tree may be described by
111       its index which is just a string of characters. The lookup algorithm
112       starts at the root frame and interprets the index string character by
113       character as follows:
114
115       ·   0: select the first subtree
116
117       ·   1: select the second subtree
118
119       ·   .: select the subtree having the focus
120
121       ·   /: select the subtree not having the focus
122
123       ·   @: select the frame having the focus. In contrast to ., this passes
124           multiple layers all down to the focused leaf of the frame tree.
125
126       ·   p: select the parent tree
127
128       ·   e: finds a suitable empty frame: if the focused frame is not empty,
129           this selects the closest frame that is empty (in any subtree)
130
131       For example:
132
133       ·   An empty string refers to the root frame
134
135       ·   00 refers to the first subtree of the first subtree of the root
136           frame.
137
138       ·   1e refers to the first empty frame in the second subtree.
139
140       ·   /@ refers to the focused frame within the unfocused "half" of the
141           frame tree
142
143       ·   @p/ refers to the sibling of the focused frame
144

TAGS

146       Tags are very similar to workspaces, virtual desktops or window groups.
147       Each tag has one layout. There is a list of tags. You can add or remove
148       tags dynamically.
149

MONITORS

151       Monitors in herbstluftwm are totally independent of the actual physical
152       screens. This means you can for example split your screen in two
153       virtual monitors to view two tags at once on a big screen.
154
155       Each monitor displays exactly one tag on a specified rectangle on the
156       screen.
157
158       Each monitor may have a name, which can be set via add_monitor and
159       rename_monitor. It can be unset with the rename_monitor command. A
160       monitor name is an arbitrary non-empty string which must not start with
161       +, - or any digit.
162
163       A monitor can be referenced in different ways:
164
165       ·   by its absolute index as listed in the list_monitors command.
166
167       ·   by its relative index: a + or - followed by a delta, e.g.: +3
168
169       ·   by its relative position to the focused monitor.  -l denotes the
170           monitor left of the focused monitor, -r right of, -u above of, and
171           -d below of, respectively.
172
173       ·   by "" (an empty string) which represents the current monitor.
174
175       ·   by its name.
176

COMMANDS

178       herbstluftwm is controlled by internal commands, which can be executed
179       via herbstclient(1) or via keybindings.
180
181       quit
182           Quits herbstluftwm.
183
184       reload
185           Executes the autostart file.
186
187       version
188           Prints the version of the running herbstluftwm instance.
189
190       echo [ARGS ...]
191           Prints all given ARGS separated by a single space and a newline
192           afterwards.
193
194       true
195           Ignores all arguments and always returns success, i.e. 0.
196
197       false
198           Ignores all arguments and always returns failure, i.e. 1.
199
200       list_commands
201           Lists all available commands.
202
203       list_monitors
204           List currently configured monitors with their index, area (as
205           rectangle), name (if named) and currently viewed tag.
206
207       list_rules
208           Lists all active rules. Each line consists of all the parameters
209           the rule was called with, plus its label, separated by tabs.
210
211       list_keybinds
212           Lists all bound keys with their associated command. Each line
213           consists of one key combination and the command with its parameters
214           separated by tabs.
215
216           Warning
217           Tabs within command parameters are not escaped!
218
219       lock
220           Increases the monitors_locked setting. Use this if you want to do
221           multiple window actions at once (i.e. without repainting between
222           the single steps). See also: unlock
223
224       unlock
225           Decreases the monitors_locked setting. If monitors_locked is
226           changed to 0, then all monitors are repainted again. See also: lock
227
228       keybind KEY COMMAND [ARGS ...]
229           Adds a key binding. When KEY is pressed, the internal COMMAND (with
230           its ARGS) is executed. A key binding is a (possibly empty) list of
231           modifiers (Mod1, Mod2, Mod3, Mod4, Mod5, Alt, Super, Control/Ctrl,
232           Shift) and one key (see keysymdef.h for a list of keys). Modifiers
233           and the key are concatenated with - or + as separator. If there is
234           already a binding for this KEY, it will be overwritten. Examples:
235
236           ·   keybind Mod4+Ctrl+q quit
237
238           ·   keybind Mod1-i toggle always_show_frame
239
240           ·   keybind Mod1-Shift-space cycle_layout -1
241
242       keyunbind KEY|-F|--all
243           Removes the key binding for KEY. The syntax for KEY is defined in
244           keybind. If -F or --all is given, then all key bindings will be
245           removed.
246
247       mousebind BUTTON ACTION [COMMAND ...]
248           Adds a mouse binding for the floating mode. When BUTTON is pressed,
249           the specified ACTION will be performed.  BUTTON has a similar
250           syntax to the KEY argument of keybind: It consists of a list of
251           modifiers (separated by - or +, valid modifiers are listed in the
252           description of keybind) and exactly one button name:
253
254           ·   B1 or Button1
255
256           ·   B2 or Button2
257
258           ·   B3 or Button3
259
260           ·   B4 or Button4
261
262           ·   B5 or Button5
263
264           ACTION must be one of the following actions:
265
266           ·   move: Moves the window by dragging the cursor.
267
268           ·   resize: Resizes the window by dragging a corner.
269
270           ·   zoom: Resizes the window into all four directions while keeping
271               the center of the window constant.
272
273           ·   call: Only calls the specified COMMAND while client.dragged
274               links to the client on which the BUTTON has been performed.
275
276           While an ACTION is performed, client.dragged is the client which is
277           dragged. E.g.:
278
279           ·   mousebind Mod1-Button3 zoom
280
281           ·   mousebind Mod1-B4 call substitute WID clients.dragged.winid
282               spawn transset-df --inc -i WID 0.05
283
284           ·   mousebind Mod1-B5 call substitute WID clients.dragged.winid
285               spawn transset-df --dec -i WID -m 0.2 0.05
286
287       drag WINID ACTION
288           Starts dragging the specified client window WINID with the
289           specified ACTION (see mousebind). E.g.  drag '' resize starts
290           resizing the focused window.
291
292       mouseunbind
293           Removes all mouse bindings.
294
295       spawn EXECUTABLE [ARGS ...]
296           Spawns an EXECUTABLE with its ARGS. For details see man 3 execvp.
297           Example:
298
299           ·   spawn xterm -e man 3 execvp
300
301       wmexec [WINDOWMANAGER [ARGS ...]]
302           Executes the WINDOWMANAGER with its ARGS. This is useful to switch
303           the window manager in the running session without restarting the
304           session. If no or an invalid WINDOWMANAGER is given, then
305           herbstluftwm is restarted. For details see man 3 execvp. Example:
306
307           ·   wmexec openbox
308
309       chain SEPARATOR [COMMANDS ...]
310           chain expects a SEPARATOR and a list of COMMANDS with arguments.
311           The commands have to be separated by the specified SEPARATOR. The
312           SEPARATOR can by any word and only is recognized as the separator
313           between commands if it exactly matches SEPARATOR. "chain" outputs
314           the appended outputs of all commands and returns the exit code of
315           the last executed command. Examples are:
316
317           ·   Create a tag called "foo" and directly use it:
318
319               chain , add foo , use foo
320
321           ·   Rotate the layout clockwise:
322
323               chain .-. lock .-. rotate .-. rotate .-. rotate .-. unlock
324
325           Counterexamples are:
326
327           ·   This will only create a tag called "foo,":
328
329               chain , add foo, use foo
330
331           ·   Separator "." defined, but "," is used:
332
333               chain . add foo , use foo
334
335       and SEPARATOR [COMMANDS ...]
336           "and" behaves like the chain command but only executes the
337           specified COMMANDS while the commands return the exit code 0.
338
339       or SEPARATOR [COMMANDS ...]
340           "or" behaves like the chain command but only executes the specified
341           COMMANDS until one command returns the exit code 0.
342
343       ! COMMAND
344           "!" executes the provided command, but inverts its return value. If
345           the provided command returns a nonzero, "!" returns a 0, if the
346           command returns a zero, "!" returns a 1.
347
348       try COMMAND
349           "try" executes the provided command, prints its output, but always
350           returns success, i.e. 0.
351
352       silent COMMAND
353           "silent" executes the provided command, but discards its output and
354           only returns its exit code.
355
356       focus_nth INDEX
357           Focuses the nth window in a frame. The first window has INDEX 0. If
358           INDEX is negative or greater than the last window index, then the
359           last window is focused.
360
361       cycle [DELTA]
362           Cycles the selection within the current frame by DELTA. If DELTA is
363           omitted, DELTA = 1 will be used.  DELTA can be negative; DELTA = -1
364           means: cycle in the opposite direction by 1.
365
366       cycle_all [--skip-invisible] [DIRECTION]
367           Cycles through all non-minimized windows and frames on the current
368           tag.  DIRECTION = 1 means forward (default value), DIRECTION = -1
369           means backward, DIRECTION = 0 has no effect. If there are multiple
370           windows within one frame, then it acts similar to the cycle
371           command. If --skip-invisible is given, then this only cycles
372           through all visible windows and skips invisible windows in the max
373           layout (the flag only affects invisible windows in the max layout;
374           minimized windows are always skipped). After each focus change, the
375           focused window is raised.
376
377       cycle_frame [DIRECTION]
378           Cycles through all frames on the current tag.  DIRECTION = 1 means
379           forward, DIRECTION = -1 means backward, DIRECTION = 0 has no
380           effect.  DIRECTION defaults to 1.
381
382       cycle_layout [DELTA [LAYOUTS ...]]
383           Cycles the layout algorithm in the current frame by DELTA.  DELTA
384           defaults to 1. You can find a list of layout algorithms above. If a
385           list of LAYOUTS is given, cycle_layout will cycle through those
386           instead of the default layout algorithm list. This is done by
387           finding the first occurrence of the current layout in LAYOUTS and
388           picking the next layout according to DELTA. If the current layout
389           doesn’t occur in LAYOUTS, the first entry is picked. Example:
390
391           ·   cycle_layout -1
392
393           ·   cycle_layout 1 vertical grid
394
395       set_layout LAYOUT
396           Sets the layout algorithm in the current frame to LAYOUT. For the
397           list of layouts, check the list of layout algorithms above.
398
399       close WINID
400           Closes the specified window gracefully or the focused window if
401           none is given explicitly. See the section on WINDOW IDS how to
402           reference a certain window.
403
404       close_or_remove
405           Closes the focused window or removes the current frame if no window
406           is focused. In floating mode, this acts as the close command.
407
408       close_and_remove
409           Closes the focused window and removes the current frame if no other
410           window is present in that frame. In floating mode, this acts as the
411           close command.
412
413       split ALIGN [FRACTION [FRAMEINDEX]
414           Splits the focused frame (or the frame specified by FRAMEINDEX, see
415           the section frame index) into two subframes with a specified
416           FRACTION between 0 and 1 which defaults to 0.5.  ALIGN is one of
417
418
419           ·   top
420
421           ·   bottom (= vertical)
422
423           ·   left,
424
425           ·   right (= horizontal)
426
427           ·   explode
428
429           ·   auto (split along longest side)
430
431               It specifies which of the two halves will be empty after the
432               split. The other half will be occupied by the currently focused
433               frame. After splitting, the originally focused frame will stay
434               focused. One special ALIGN mode is explode, which splits the
435               frame in such a way that the window sizes and positions are
436               kept as much as possible. If no FRACTION is given to explode
437               mode an optimal fraction is picked automatically. Example:
438
439           ·   split explode
440
441           ·   split bottom 0.5
442
443           ·   split horiz 0.3
444
445           ·   split vertical 0.5
446
447           ·   split h
448
449           ·   split top 0.2 '' (splits the root frame)
450
451       focus [-i|-e] DIRECTION
452           Moves the focus from current frame to the next frame or client in
453           DIRECTION which is in:
454
455
456           ·   l[eft]
457
458           ·   r[ight]
459
460           ·   u[p]
461
462           ·   d[own]
463
464           If -i (internal) is given or default_direction_external_only is
465           unset, then the next client in DIRECTION can also be within the
466           same frame. If there is no client within this frame or -e
467           (external) is given, then the next frame in specified DIRECTION
468           will be focused.
469
470
471           The direction between frames is defined as follows: The focus is in
472           a leaf of the binary tree. Each inner node in the tree remembers
473           the last focus direction (child 0 or child 1). The algorithm uses
474           the shortest possible way from the leaf (the currently focused
475           frame) to the root until it is possible to change focus in the
476           specified DIRECTION. From there the focus goes back to the leaf.
477
478
479           Example: The focus is at frame A. After executing focus right focus
480           will be at frame C.
481
482                Tree:  H,0     Screen: ┌─────┐┌─────┐ (before)
483                       ╱ ╲             │  B  ││  C  │
484                      ╱   ╲            └─────┘└─────┘
485                    V,1   V,0          ┌─────┐┌─────┐
486                    ╱ ╲   ╱ ╲          │  A* ││  D  │
487                   B  A* C   D         └─────┘└─────┘
488
489                Tree:  H,1     Screen: ┌─────┐┌─────┐ (after focus right)
490                       ╱ ╲             │  B  ││  C* │
491                      ╱   ╲            └─────┘└─────┘
492                    V,1   V,0          ┌─────┐┌─────┐
493                    ╱ ╲   ╱ ╲          │  A  ││  D  │
494                   B   A C*  D         └─────┘└─────┘
495
496           If the currently focused client is floated, then the next floating
497           window in the specified direction is focused and raised.
498
499           If focus_crosses_monitor_boundaries is set and no client or frame
500           is found in the specified DIRECTION, then the next monitor in that
501           DIRECTION is focused.
502
503       focus_edge [-i|-e] DIRECTION
504           Focuses the window on the edge of the tag in the specified
505           DIRECTION. The DIRECTIONS and -e behave as specified at the focus
506           command.
507
508
509           If -i (internal) is given or default_direction_external_only is
510           unset, then the window on the edge of the tag will be focused.
511           Else, only the frame on the edge of the tag will be focused, and
512           the window that was last focused in that frame will be focused.
513
514       raise WINID
515           Raises the specified window. See the section on WINDOW IDS on how
516           to reference a certain window. Its result is only visible in
517           floating mode.
518
519           Tip
520           The WINID also can specify an unmanaged window, although the
521           completion for the raise command does not list the IDs of unmanaged
522           windows.
523
524       jumpto WINID
525           Puts the focus to the specified window. See the section on WINDOW
526           IDS on how to reference a certain window.
527
528       bring WINID
529           Moves the specified window to the current frame and focuses it.
530           Floating windows are brought to the current tag, but keep their
531           floating state. See the section on WINDOW IDS on how to reference a
532           certain window.
533
534       resize DIRECTION [FRACTIONDELTA]
535           Changes the size of the focused frame in the specified DIRECTION by
536           FRACTIONDELTA (which defaults to 0.02 if none is supplied).
537           DIRECTION behaves as specified at the focus command. If a floating
538           window is focused, it grows towards next edge, i.e. either the edge
539           of the next window or the monitor edge in the specified DIRECTION
540           (FRACTIONDELTA is ignored in that case). Example:
541
542           ·   resize right +0.05
543
544           ·   resize down -0.1
545
546       shift_edge [-i|-e] DIRECTION
547           Shifts the focused window to the the edge of a tag in the specified
548           DIRECTION. The DIRECTIONS behave as specified at the focus command
549           and -i and -e behave as specified at the focus_edge command.
550
551       shift [-i|-e] DIRECTION
552           Shifts the focused window to the next frame in the specified
553           DIRECTION. The DIRECTIONS and -i|-e behave as specified at the
554           focus command. If the focused client is floated instead of being
555           tiled, then client is shifted to the next window or screen edge.
556
557       shift_to_monitor MONITOR
558           Moves the focused window to the tag on the specified MONITOR. See
559           the MONITORS section, how to address a monitor.
560
561       remove
562           Removes focused frame and merges its windows to its closest
563           neighbour frame.
564
565       rotate
566           Rotates the layout on the focused tag counterclockwise by 90
567           degrees. This only manipulates the alignment of frames, not the
568           content of them.
569
570       mirror [vertical|horizontal|both]
571           Mirrors the layout on the focused tag vertically, horizontally, or
572           both; the default is horizontal. This command only manipulates the
573           alignment of frames, not the content of them.
574
575       set NAME VALUE
576           Sets the specified setting NAME to VALUE. Allowed values for
577           boolean settings are on or true for on, off or false for off,
578           toggle to toggle its value. All SETTINGS are listed in the section
579           below.
580
581       get NAME
582           Prints the value of setting NAME. All SETTINGS are listed in the
583           section below.
584
585       toggle NAME
586           Toggles the setting NAME if it’s a boolean setting.
587
588       cycle_value NAME VALUES ...
589           Cycles value of the setting NAME through VALUES: I.e. it searches
590           the first occurrence of the current value in VALUES and changes the
591           value to the next in the list or to the first one if the end is
592           reached or current value wasn’t found. Example:
593
594           ·   cycle_value frame_gap 0 5 10 15
595
596           ·   cycle_value frame_bg_normal_color red green blue
597
598       cycle_monitor [DELTA]
599           Cycles monitor focused by DELTA.  DELTA defaults to 1.
600
601       focus_monitor MONITOR
602           Puts focus to the specified monitor. See the MONITORS section, how
603           to address a monitor.
604
605       add TAG
606           Creates a new empty tag named TAG.
607
608       use TAG
609           Switches the focused monitor to specified TAG.
610
611       use_index INDEX [--skip-visible]
612           Switches the focused monitor to the TAG with the specified INDEX.
613           If INDEX starts with + or -, then INDEX is treated relative to the
614           current TAG. If --skip-visible is passed and INDEX is relative,
615           then tags that are already visible on a monitor are skipped. E.g.
616           this cycles backwards through the tags:
617
618           ·   use_index -1 --skip-visible
619
620       use_previous
621           Switches the focused monitor to the previously viewed tag.
622
623       merge_tag TAG [TARGET]
624           Removes tag named TAG and moves all its windows to tag TARGET. If
625           TARGET is omitted, the focused tag will be used.
626
627       rename OLDTAG NEWTAG
628           Renames tag named OLDTAG to NEWTAG.
629
630       move TAG
631           Moves the focused window to the tag named TAG.
632
633       move_index INDEX [--skip-visible]
634           Moves the focused window to the tag specified by INDEX. Analogical
635           to the argument for use_index: If INDEX starts with + or -, then it
636           is treated relative. If --skip-visible is passed with a relative
637           index, then already visible tags are skipped.
638
639       lock_tag [MONITOR]
640           Lock the tag switching on the specified monitor. If no argument is
641           given, the currently focused monitor is used. When the tag
642           switching is disabled for a monitor, the commands use and use_index
643           have no effect when executed there. When swap_monitors_to_get_tag
644           is enabled, switching to a tag which is located on a locked
645           monitor, switches to that monitor instead of stealing it from
646           there. The lock state of a monitor is indicated by "[LOCKED]" in
647           the list_monitors output.
648
649       unlock_tag [MONITOR]
650           Re-enables the tag switching on the specified monitor. If no
651           argument is given, the currently focused monitor is used. This is
652           the reverse operation to lock_tag and has no further side effects
653           but removing this lock.
654
655       disjoin_rects RECTS ...
656           Takes a list of rectangles and splits them into smaller pieces
657           until all rectangles are disjoint, the result rectangles are
658           printed line by line. This command does not modify the current list
659           of monitors! So this can be useful in combination with the
660           set_monitors command.
661
662           ·   E.g.  disjoin_rects 600x400+0+0 600x400+300+250 prints this:
663
664                   300x150+300+250
665                   600x250+0+0
666                   300x150+0+250
667                   300x150+600+250
668                   600x250+300+400
669
670           ·   In the above example two monitors are split into 5 monitors,
671               which graphically means:
672
673                   ┌──────┐                  ┌──────┐
674                   │      │                  └──────┘
675                   │  ┌───┼───┐              ┌─┐┌───┐┌──┐
676                   │  │   │   │   disjoin    │ ││   ││  │
677                   └──┼───┘   │  ─────────>  └─┘└───┘└──┘
678                      │       │                 ┌───────┐
679                      └───────┘                 └───────┘
680
681       set_monitors RECTS ...
682           Sets the list of monitors exactly to the list of given rectangles:
683
684           ·   The i’th existing monitor is moved to the i’th given RECT
685
686           ·   New monitors are created if there are more RECTS than monitors
687
688           ·   Existing monitors are deleted if there are more monitors than
689               RECTS
690
691       detect_monitors -l|--list|--list-all|--no-disjoin
692           Sets the list of monitors to the physically available monitors. If
693           both Xinerama and xrandr are missing, it will fall back to one
694           monitor across the entire screen. If the detected monitors overlap,
695           the will be split into more monitors that are disjoint but cover
696           the same area using disjoin_rects.
697
698           If -l or --list is passed, the list of rectangles of detected
699           physical monitors is printed. So hc detect_monitors is equivalent
700           to the bash command hc set_monitors $(hc disjoin_rects $(hc
701           detect_monitors -l)).
702
703           If --list-all is passed, then it is printed which multimonitor
704           detection (xinerama, xrandr) has which set of physical monitors.
705
706       add_monitor RECT [TAG [NAME]]
707           Adds a monitor on the specified rectangle RECT and displays TAG on
708           it.  TAG currently must not be displayed on any other monitor.
709           RECT is a string of the form WxH±X±Y. If no or an empty TAG is
710           given, then any free tag will be chosen. If a NAME is given, you
711           can reference to this monitor by its name instead of using an
712           index. Example:
713
714           ·   add_monitor 1024x768-20+0 mynewtag main
715
716       remove_monitor MONITOR
717           Removes the specified monitor.
718
719       move_monitor MONITOR RECT [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
720           Moves the specified monitor to rectangle RECT.  RECT is defined as
721           in add_monitor. If no or an empty pad is given, it is not changed.
722
723       raise_monitor [MONITOR]
724           Raises the specified monitor or the current one if MONITOR is
725           omitted.
726
727       rename_monitor MONITOR NAME
728           (Re)names an already existing monitor. If NAME is empty, it removes
729           the monitor’s name.
730
731       stack
732           Prints the stack of monitors with the visible tags and their layers
733           as a tree. The order of the printed stack is top to bottom. The
734           style is configured by the tree_style setting.
735
736       monitor_rect [[-p] MONITOR]
737           Prints the rectangle of the specified monitor in the format: X Y W
738           H If no MONITOR or cur is given, then the current monitor is used.
739           If -p is supplied, then the remaining rect without the pad around
740           this monitor is printed.
741
742       pad MONITOR [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
743           Sets the pad of specified monitor to the specified padding. If no
744           or an empty padding is given, it is not changed.
745
746       list_padding [MONITOR]
747           Lists the padding of the specified monitor, or the currently
748           focused monitor if no monitor is given.
749
750       layout [TAG [INDEX]]
751           Prints the layout of frame with INDEX on TAG, in a nice tree style.
752           Its style is defined by the tree_style setting. If no TAG is given,
753           the current tag is used. If no INDEX is given, the root frame is
754           used. To specify INDEX without specifying TAG (i.e. use current
755           tag), pass an empty string as TAG.
756
757           An example output is:
758
759               ╾─┐ horizontal 50% selection=1
760                 ├─╼ vertical: 0xe00009
761                 └─┐ vertical 50% selection=0
762                   ├─╼ vertical: 0xa00009 [FOCUS]
763                   └─╼ vertical: 0x1000009
764
765       dump [TAG [INDEX]]
766           Prints the same information as the layout command but in a machine
767           readable format. Its output can be read back with the load command.
768
769           An example output (formatted afterwards) is:
770
771               (split horizontal:0.500000:1
772                   (clients vertical:0 0xe00009)
773                   (split vertical:0.500000:1
774                       (clients vertical:0 0xa00009)
775                       (clients vertical:0 0x1000009)))
776
777       load [TAG] LAYOUT
778           Loads a given LAYOUT description to specified TAG or current tag if
779           no TAG is given.
780
781           Caution
782           LAYOUT is exactly one parameter. If you are calling it manually
783           from your shell or from a script, quote it properly!
784
785       complete POSITION [COMMAND ARGS ...]
786           Prints the result of tab completion for the partial COMMAND with
787           optional ARGS. You usually do not need this, because there is
788           already tab completion for bash, zsh and fish. Example:
789
790           ·   complete 0 m
791
792               prints all commands beginning with m
793
794           ·   complete 1 toggle fra
795
796               prints all settings beginning with fra that can be toggled
797
798       complete_shell POSITION [COMMAND ARGS ...]
799           Behaves like complete with the following extras, useful for
800           completion on posix shells:
801
802           ·   Escape sequences are removed in COMMAND and ARGS.
803
804           ·   A space is appended to each full completion result.
805
806           ·   Special characters will be escaped in the output.
807
808       emit_hook NAME ARGS ...
809           Emits a custom hook NAME to all idling herbstclients.
810
811       tag_status [MONITOR]
812           Print a tab separated list of all tags for the specified MONITOR
813           index. If no MONITOR index is given, the focused monitor is used.
814           Each tag name is prefixed with one char, which indicates its state:
815
816           ·   .  the tag is empty
817
818           ·   : the tag is not empty
819
820           ·   + the tag is viewed on the specified MONITOR, but this monitor
821               is not focused.
822
823           ·   # the tag is viewed on the specified MONITOR and it is focused.
824
825           ·   - the tag is viewed on a different MONITOR, but this monitor is
826               not focused.
827
828           ·   % the tag is viewed on a different MONITOR and it is focused.
829
830           ·   !  the tag contains an urgent window
831
832           Warning
833           If you use a tab in one of the tag names, then tag_status is
834           probably quite useless for you.
835
836       floating [[TAG] on|off|toggle|status]
837           Changes specified TAG to floating/tiling mode or prints its current
838           status. If no TAG is given, the current tag is used. If no argument
839           is given, floating mode is toggled. If status is given, then on or
840           off is printed, depending of the floating state of TAG.
841
842       rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
843           Defines a rule which will be applied to all new clients. Its
844           behaviour is described in the RULES section.
845
846       unrule LABEL|--all|-F
847           Removes all rules named LABEL. If --all or -F is passed, then all
848           rules are removed.
849
850       apply_rules WINID|--all
851           Apply the rules to the specified window WINID. If --all is passed,
852           then the rules are applied to all clients.
853
854       apply_tmp_rule WINID|--all [RULEDESCRIPTION...]
855           Apply the rule RULEDESCRIPTION to one particular client WINID or
856           all clients (--all) without adding the rule to the rule list. The
857           RULEDESCRIPTION specifies a rule consisting of conditions and
858           consequences as one would pass it to the rule command as described
859           in the RULES section. This allows testing rules before adding them.
860           Running apply_tmp_rule only applies the particular rule given in
861           the arguments and ignores the existing rules.
862
863       fullscreen [on|off|toggle]
864           Sets or toggles the fullscreen state of the focused client. If no
865           argument is given, fullscreen mode is toggled.
866
867       pseudotile [on|off|toggle]
868           Sets or toggles the pseudotile state of the focused client. If a
869           client is pseudotiled, then in tiling mode the client is only moved
870           but not resized - the client size will stay the floating size. The
871           only reason to resize the client is to ensure that it fits into its
872           tile. If no argument is given, pseudotile mode is toggled.
873
874       object_tree [PATH]
875           Prints the tree of objects. If the object path PATH is given, only
876           the subtree starting at PATH is printed. See the OBJECTS section
877           for more details.
878
879       attr [PATH [NEWVALUE]
880           Prints the children and attributes of the given object addressed by
881           PATH. If PATH is an attribute, then print the attribute value. If
882           NEWVALUE is given, assign NEWVALUE to the attribute given by PATH.
883           See the OBJECTS section for more details.
884
885       get_attr ATTRIBUTE
886           Print the value of the specified ATTRIBUTE as described in the
887           OBJECTS section.
888
889       set_attr ATTRIBUTE NEWVALUE
890           Assign NEWVALUE to the specified ATTRIBUTE as described in the
891           OBJECTS section.
892
893       new_attr bool|color|int|string|uint PATH [VALUE]
894           Creates a new attribute with the name and in the object specified
895           by PATH. Its type is specified by the first argument. The attribute
896           name has to begin with my_. If VALUE is supplied, then it is
897           written to the attribute (if this fails the attribute still
898           remains).
899
900       remove_attr PATH
901           Removes the user defined attribute PATH.
902
903       substitute IDENTIFIER ATTRIBUTE COMMAND [ARGS ...]
904           Replaces all exact occurrences of IDENTIFIER in COMMAND and its
905           ARGS by the value of the ATTRIBUTE. Note that the COMMAND also is
906           replaced by the attribute value if it equals IDENTIFIER. The
907           replaced command with its arguments then is executed. Example:
908
909           ·   substitute MYTITLE clients.focus.title echo MYTITLE
910
911               Prints the title of the currently focused window.
912
913       sprintf IDENTIFIER FORMAT [FORMATARG ...] COMMAND [CMDARGS ...]
914           Replaces all exact occurrences of IDENTIFIER in COMMAND and its
915           CMDARGS by the string specified by FORMAT. The FORMAT string may
916           contain several placeholders, similar to the printf(1) command:
917
918           ·   %s inserts an attribute value whose path is given by the string
919               value of the next FORMATARG
920
921           ·   %c ("constant") inserts the next FORMATARG without
922               modification.
923
924           ·   %% stands for a plain %
925
926           The replaced command with its arguments then is executed. Examples:
927
928           ·   sprintf STR title=%s clients.focus.title echo STR
929
930               Prints the title of the currently focused window prepended by
931               title=.
932
933           ·   sprintf X "%c %s tags" "there are" tags.count echo X
934
935               Prints there are N tags with N replaced by the number of tags.
936
937           ·   sprintf X tag=%s tags.focus.name rule once X
938
939               Moves the next client that appears to the tag that is currently
940               focused.
941
942           ·   sprintf X %s/%s tags.focus.index tags.count echo X
943
944               Tells which tag is focused and how many tags there are
945
946           ·   sprintf l somelongstring echo l l l
947
948               Prints somelongstring three times, separated by spaces.
949
950           ·   substitute X tags.count sprintf Y "number=%c" X echo Y
951
952               has the same output as
953
954               sprintf Y "number=%s" tags.count echo Y
955
956               (Note how the %c changes to %s)
957
958       foreach IDENTIFIER OBJECT COMMAND [ARGS ...]
959           For each child of the given OBJECT the COMMAND is called with its
960           ARGS, where the IDENTIFIER is replaced by the path of the child.
961           The exit code is the exit code of the command executed last.
962           Examples:
963
964           ·   foreach T tags.by-name. echo T
965
966               Prints:
967
968                   tags.by-name.1
969                   tags.by-name.2
970                   tags.by-name.3
971                   [...]
972
973           ·   Note that foreach only iterates over children, but not over
974               attributes, so foreach S settings echo S prints nothing, since
975               the settings object has only attributes but no child objects.
976
977           ·   foreach C clients. echo C prints the object paths of all
978               clients, but the focused client twice, because it is mentioned
979               in clients.  twice: by window id and as clients.focus.
980
981       mktemp [bool|int|string|uint] IDENTIFIER COMMAND [ARGS ...]
982           Creates a temporary attribute with the given type and replaces all
983           occurrences of IDENTIFIER in COMMAND and ARGS by the path of the
984           temporary attribute. The replaced command with its arguments is
985           executed then. The exit status of COMMAND is returned.
986
987       compare ATTRIBUTE OPERATOR VALUE
988           Compares the value of ATTRIBUTE with VALUE using the comparison
989           method OPERATOR. If the comparison succeeds, it returns 0, else 1.
990           The operators are:
991
992           ·   =: ATTRIBUTE's value equals VALUE
993
994           ·   !=: ATTRIBUTE's value does not equal VALUE
995
996           ·   le: ATTRIBUTE's value <= VALUE
997
998           ·   lt: ATTRIBUTE's value < VALUE
999
1000           ·   ge: ATTRIBUTE's value >= VALUE
1001
1002           ·   gt: ATTRIBUTE's value > VALUE
1003
1004           The OPERATORs le,lt,ge,gt can only be used if ATTRIBUTE is of the
1005           type integer or unsigned integer. Note that the first parameter
1006           must always be an attribute and the second a constant value. If you
1007           want to compare two attributes, use the substitute command:
1008
1009               substitute FC tags.focus.frame_count \
1010                   compare tags.focus.client_count gt FC
1011
1012           It returns success if there are more clients on the focused tag
1013           than frames.
1014
1015       getenv NAME
1016           Gets the value of the environment variable NAME.
1017
1018       setenv NAME VALUE
1019           Set the value of the environment variable NAME to VALUE. See the
1020           export command for a convenience wrapper.
1021
1022       unsetenv NAME
1023           Unsets the environment variable NAME.
1024
1025       export NAME=VALUE
1026           Set the value of the environment variable NAME to VALUE. The syntax
1027           is the same as for export in unix shells (notice that there is a
1028           =). Intuitively, if you forgot to run export FOO=BAR before
1029           starting herbstluftwm, you can run herbstclient export FOO=BAR from
1030           within your herbstluftwm session for the same effect. The export
1031           command is the same as the setenv command with different syntax.
1032

SETTINGS

1034       Settings configure the behaviour of herbstluftwm and can be controlled
1035       via the set, get and toggle commands. The following list mentions all
1036       settings and their type. The settings can also be accessed via the
1037       object tree (see the section OBJECTS).
1038
1039       frame_gap (Integer)
1040           The gap between frames in the tiling mode.
1041
1042       frame_padding (Integer)
1043           The padding within a frame in the tiling mode, i.e. the space
1044           between the border of a frame and the windows within it.
1045
1046       window_gap (Integer)
1047           The gap between windows within one frame in the tiling mode.
1048
1049       snap_distance (Integer)
1050           If a client is dragged in floating mode, then it snaps to neighbour
1051           clients if the distance between them is smaller than snap_distance.
1052
1053       snap_gap (Integer)
1054           Specifies the remaining gap if a dragged client snaps to an edge in
1055           floating mode. If snap_gap is set to 0, no gap will remain.
1056
1057       mouse_recenter_gap (Integer)
1058           Specifies the gap around a monitor. If the monitor is selected and
1059           the mouse position would be restored into this gap, it is set to
1060           the center of the monitor. This is useful, when the monitor was
1061           left via mouse movement, but is reselected by keyboard. If the gap
1062           is 0 (default), the mouse is never recentered.
1063
1064       frame_border_active_color (String/Color)
1065           The border color of a focused frame.
1066
1067       frame_border_normal_color (String/Color)
1068           The border color of an unfocused frame.
1069
1070       frame_border_inner_color (String/Color)
1071           The color of the inner border of a frame.
1072
1073       frame_bg_active_color (String/Color)
1074           The fill color of a focused frame.
1075
1076       frame_bg_normal_color (String/Color)
1077           The fill color of an unfocused frame (It is only visible if
1078           always_show_frame is set).
1079
1080       frame_bg_transparent (Integer)
1081           If set, the background of frames are transparent. That means a
1082           rectangle is cut out from the inner such that only the frame border
1083           and a stripe of width frame_transparent_width can be seen. Use
1084           frame_active_opacity and frame_normal_opacity for real
1085           transparency.
1086
1087       frame_transparent_width (Integer)
1088           Specifies the width of the remaining frame colored with
1089           frame_bg_active_color if frame_bg_transparent is set.
1090
1091       frame_border_width (Integer)
1092           Border width of a frame.
1093
1094       frame_border_inner_width (Integer)
1095           The width of the inner border of a frame. Must be less than
1096           frame_border_width, since it does not add to the frame border width
1097           but is a part of it.
1098
1099       focus_crosses_monitor_boundaries (Boolean)
1100           If set, the focus command crosses monitor boundaries. If there is
1101           no client in the direction given to focus, then the monitor in the
1102           specified direction is focused.
1103
1104       raise_on_focus (Boolean)
1105           If set, a window is raised if it is focused. The value of this
1106           setting is only used in floating mode.
1107
1108       raise_on_focus_temporarily (Boolean)
1109           If set, a window is raised temporarily if it is focused on its tag.
1110           Temporarily in this case means that the window will return to its
1111           previous stacking position if another window is focused.
1112
1113       raise_on_click (Boolean)
1114           If set, a window is raised if it is clicked. The value of this
1115           setting is only noticed in floating mode.
1116
1117       window_border_width (Integer)
1118           Border width of a window.  Warning: This only exists for
1119           compatibility reasons; it is only an alias for the attribute
1120           theme.border_width.
1121
1122       window_border_inner_width (Integer)
1123           The width of the inner border of a window. Must be less than
1124           window_border_width, since it does not add to the window border
1125           width but is a part of it.  Warning: This only exists for
1126           compatibility reasons; it is only an alias for the attribute
1127           theme.inner_width.
1128
1129       window_border_active_color (String/Color)
1130           Border color of a focused window.  Warning: This only exists for
1131           compatibility reasons; it is only an alias for the attribute
1132           theme.active.color.
1133
1134       window_border_normal_color (String/Color)
1135           Border color of an unfocused window.  Warning: This only exists for
1136           compatibility reasons; it is only an alias for the attribute
1137           theme.normal.color.
1138
1139       window_border_urgent_color (String/Color)
1140           Border color of an unfocused but urgent window.  Warning: This only
1141           exists for compatibility reasons; it is only an alias for the
1142           attribute theme.urgent.color.
1143
1144       window_border_inner_color (String/Color)
1145           Color of the inner border of a window.  Warning: This only exists
1146           for compatibility reasons; it is only an alias for the attribute
1147           theme.inner_color.
1148
1149       always_show_frame (Boolean)
1150           If set, all frames are displayed. If unset, only frames with focus
1151           or with windows in them are displayed.
1152
1153       frame_active_opacity (Integer)
1154           Focused frame opacity in percent. Requires a running compositing
1155           manager to take actual effect.
1156
1157       frame_normal_opacity (Integer)
1158           Unfocused frame opacity in percent. Requires a running compositing
1159           manager to take actual effect.
1160
1161       default_frame_layout (Integer)
1162           Index of the frame layout, which is used if a new frame is created
1163           (by split or on a new tag). For a list of valid indices and their
1164           meanings, check the list of layout algorithms above.
1165
1166       default_direction_external_only (Boolean)
1167           This setting controls the behaviour of focus and shift if no -e or
1168           -i argument is given. If set, then focus and shift changes the
1169           focused frame even if there are other clients in this frame in the
1170           specified DIRECTION. Else, a client within current frame is
1171           selected if it is in the specified DIRECTION.
1172
1173       gapless_grid (Boolean)
1174           This setting affects the size of the last client in a frame that is
1175           arranged by grid layout. If set, then the last client always fills
1176           the gap within this frame. If unset, then the last client has the
1177           same size as all other clients in this frame.
1178
1179       hide_covered_windows (Boolean)
1180           If activated, windows are explicitly hidden when they are covered
1181           by another window in a frame with max layout. This only has a
1182           visible effect if a compositor is used. If activated, shadows do
1183           not stack up and transparent windows show the wallpaper behind them
1184           instead of the other clients in the max layout.
1185
1186       smart_frame_surroundings (Boolean)
1187           If set, frame borders and gaps will be removed when there’s no
1188           ambiguity regarding the focused frame.
1189
1190       smart_window_surroundings (Boolean)
1191           If set, window borders and gaps will be removed and minimal when
1192           there’s no ambiguity regarding the focused window. This minimal
1193           window decoration can be configured by the theme.minimal object.
1194
1195       focus_follows_mouse (Boolean)
1196           If set and a window is focused by mouse cursor, this window is
1197           focused (this feature is also known as sloppy focus). If unset, you
1198           need to click to change the window focus by mouse.
1199
1200
1201           If another window is hidden by the focus change (e.g. when having
1202           pseudotiled windows in the max layout) then an extra click is
1203           required to change the focus.
1204
1205       focus_stealing_prevention (Boolean)
1206           If set, only pagers and taskbars are allowed to change the focus.
1207           If unset, all applications can request a focus change.
1208
1209       monitors_locked (Integer)
1210           If greater than 0, then the clients on all monitors aren’t moved or
1211           resized anymore. If it is set to 0, then the arranging of monitors
1212           is enabled again, and all monitors are rearranged if their content
1213           has changed in the meantime. You should not change this setting
1214           manually due to concurrency issues; use the commands lock and
1215           unlock instead.
1216
1217       swap_monitors_to_get_tag (Boolean)
1218           If set: If you want to view a tag, that already is viewed on
1219           another monitor, then the monitor contents will be swapped and you
1220           see the wanted tag on the focused monitor. If not set, the other
1221           monitor is focused if it shows the desired tag.
1222
1223       auto_detect_monitors (Boolean)
1224           If set, detect_monitors is automatically executed every time a
1225           monitor is connected, disconnected or resized.
1226
1227       auto_detect_panels (Boolean)
1228           If set, EWMH panels are automatically detected and reserve space at
1229           the side of the monitors they are on (via pad attributes of each
1230           monitor). This setting is activated per default.
1231
1232       tree_style (String)
1233           It contains the chars that are used to print a nice ascii tree. It
1234           must contain at least 8 characters. e.g.  X|:#+*-.  produces a tree
1235           like:
1236
1237               X-.
1238                 #-. child 0
1239                 | #-* child 00
1240                 | +-* child 01
1241                 +-. child 1
1242                 : #-* child 10
1243                 : +-* child 11
1244
1245           Useful values for tree_style are: ╾│ ├└╼─┐ or -| |'--.  or ╾│
1246           ├╰╼─╮.
1247
1248       wmname (String)
1249           It controls the value of the _NET_WM_NAME property on the root
1250           window, which specifies the name of the running window manager. The
1251           value of this setting is not updated if the actual _NET_WM_NAME
1252           property on the root window is changed externally. Example usage:
1253
1254           ·   cycle_value wmname herbstluftwm LG3D
1255
1256       pseudotile_center_threshold (Integer)
1257           If greater than 0, it specifies the least distance between a
1258           centered pseudotile window and the border of the frame or tile it
1259           is assigned to. If this distance is lower than
1260           pseudotile_center_threshold, it is aligned to the top left of the
1261           client’s tile.
1262
1263       update_dragged_clients (Integer)
1264           If set, a client’s window content is resized immediately during
1265           resizing it with the mouse. If unset, the client’s content is
1266           resized after the mouse button is released.
1267
1268       verbose (Boolean)
1269           If set, verbose output is logged to herbstluftwm’s stderr. The
1270           default value is controlled by the --verbose command line flag.
1271

RULES

1273       Rules are used to change default properties for certain clients when
1274       they appear or when the apply_rules command is called. Each rule
1275       matches against a certain subset of all clients and defines a set of
1276       properties for them (called CONSEQUENCEs). A rule can be defined with
1277       this command:
1278
1279       rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
1280
1281       Each rule consists of a list of FLAGs, CONDITIONs, CONSEQUENCEs and,
1282       optionally, a LABEL. (each of them can be optionally prefixed with two
1283       dashes (--) to provide a more iptables(8)-like feeling).
1284
1285       Each rule can be given a custom label by specifying the LABEL property:
1286
1287       ·   [--]label=VALUE
1288
1289       If multiple labels are specified, the last one in the list will be
1290       applied. If no label is given, then the rule will be given an integer
1291       name that represents the index of the rule since the last unrule -F
1292       command (which is triggered in the default autostart).
1293
1294           Tip
1295           Rule labels default to an incremental index. These default labels
1296           are unique, unless you assign a different rule a custom integer
1297           LABEL. Default labels can be captured with the printlabel flag.
1298
1299       If a new client appears, herbstluftwm tries to apply each rule to this
1300       new client as follows: If each CONDITION of this rule matches against
1301       this client, then every CONSEQUENCE is executed. (If there are no
1302       conditions given, then this rule is executed for each client)
1303
1304       Each CONDITION consists of a property name, an operator and a value.
1305       Valid operators are:
1306
1307       ·   ~ matches if client’s property is matched by the regex value.
1308
1309       ·   = matches if client’s property string is equal to value.
1310
1311       Valid properties are:
1312
1313       instance
1314           the first entry in client’s WM_CLASS.
1315
1316       class
1317           the second entry in client’s WM_CLASS.
1318
1319       title
1320           client’s window title.
1321
1322       pid
1323           the client’s process id (Warning: the pid is not available for
1324           every client. This only matches if the client sets _NET_WM_PID to
1325           the pid itself).
1326
1327       pgid
1328           this client’s process group id. Since the pgid of a window is
1329           derived from its pid the same restrictions apply as above.
1330
1331       maxage
1332           matches if the age of the rule measured in seconds does not exceed
1333           value. This condition only can be used with the = operator. If
1334           maxage already is exceeded (and never will match again), then this
1335           rule is removed. (With this you can build rules that only live for
1336           a certain time.)
1337
1338       windowtype
1339           matches the _NET_WM_WINDOW_TYPE property of a window. If
1340           _NET_WM_WINDOW_TYPE has multiple entries, then only the first entry
1341           is used here.
1342
1343       windowrole
1344           matches the WM_WINDOW_ROLE property of a window if it is set by the
1345           window.
1346
1347       Each CONSEQUENCE consists of a NAME=VALUE pair. Valid NAMES are:
1348
1349       tag
1350           moves the client to tag VALUE.
1351
1352       monitor
1353           moves the client to the tag on monitor VALUE. If the tag
1354           consequence was also specified, and switchtag is set for the
1355           client, move the client to that tag, then display that tag on
1356           monitor VALUE. If the tag consequence was specified, but switchtag
1357           was not, ignore this consequence.
1358
1359       focus
1360           decides whether the client gets the input focus in its tag. The
1361           default is off.  VALUE can be on, off or toggle.
1362
1363       switchtag
1364           if focus is activated and the client is put to a not focused tag,
1365           then switchtag tells whether the client’s tag will be shown or not.
1366           If the tag is shown on any monitor but is not focused, the client’s
1367           tag only is brought to the current monitor if
1368           swap_monitors_to_get_tag is activated.  VALUE can be on, off or
1369           toggle.
1370
1371       manage
1372           decides whether the client will be managed or not. The default is
1373           on.  VALUE can be on, off or toggle.
1374
1375       index
1376           moves the window to a specified index in the tree.  VALUE is a
1377           frame index.
1378
1379       floating
1380           sets the floating state of the client.  VALUE can be on, off or
1381           toggle.
1382
1383       pseudotile
1384           sets the pseudotile state of the client.  VALUE can be on, off or
1385           toggle.
1386
1387       ewmhrequests
1388           sets whether the window state (the fullscreen state and the demands
1389           attention flag) can be changed by the application via ewmh itself.
1390           This does not affect the initial fullscreen state requested by the
1391           window.  VALUE can be on, off or toggle, it defaults to on.
1392
1393       ewmhnotify
1394           sets whether hlwm should let the client know about EMWH changes
1395           (currently only the fullscreen state). If this is set, applications
1396           do not change to their fullscreen-mode while still being
1397           fullscreen.  VALUE can be on, off or toggle, it defaults to on.
1398
1399       fullscreen
1400           sets the fullscreen flag of the client.  VALUE can be on or off.
1401
1402       hook
1403           emits the custom hook rule VALUE WINID when this rule is triggered
1404           by a new window with the id WINID. This consequence can be used
1405           multiple times, which will cause a hook to be emitted for each
1406           occurrence of a hook consequence.
1407
1408       keymask
1409           sets the keymask for a client (see explanation in OBJECTS).
1410
1411       keys_inactive
1412           sets a regex that determines which key bindings are inactive for a
1413           client (see explanation in OBJECTS).
1414
1415       floatplacement
1416           changes the floating position of a window. The VALUE can be one of
1417           the following:
1418
1419           ·   none does not change the placement at all
1420
1421           ·   center centers the window on the monitor
1422
1423           ·   smart tries to place it with as little overlap to other
1424               floating windows as possible. If there are multiple options
1425               with the least overlap, then the position with the least
1426               overlap to tiling windows is chosen.
1427
1428       A rule’s behaviour can be configured by some special FLAGS:
1429
1430       ·   not: negates the next CONDITION.
1431
1432       ·   !: same as not.
1433
1434       ·   once: only apply this rule once (and delete it afterwards).
1435
1436       ·   printlabel: prints the label of the newly created rule to stdout.
1437
1438       ·   prepend: prepend the rule to the list of rules instead of appending
1439           it. So its consequences may be overwritten by already existing
1440           rules.
1441
1442       Examples:
1443
1444       ·   rule --class=Netscape --tag=6 --focus=off
1445
1446           Moves all Netscape instances to tag 6, but doesn’t give focus to
1447           them.
1448
1449       ·   rule not class~.*[Tt]erm tag=2
1450
1451           Moves all clients to tag 2, if their class does not end with term
1452           or Term.
1453
1454       ·   rule class=Thunderbird index=/0
1455
1456           Insert all Thunderbird instances in the tree that has no focus and
1457           there in the first child.
1458
1459       ·   rule --windowtype=_NET_WM_WINDOW_TYPE_DIALOG --focus=on
1460
1461           Sets focus to new dialogs which set their _NET_WM_WINDOW_TYPE
1462           correctly.
1463

WINDOW IDS

1465       Several commands accept a window as reference, e.g. close. The syntax
1466       is as follows:
1467
1468       ·   an empty string — or missing argument — references the currently
1469           focused window.
1470
1471       ·   urgent references some window that is urgent.
1472
1473       ·   0xHEXID — where HEXID is some hexadecimal number — references the
1474           window with hexadecimal X11 window id HEXID.
1475
1476       ·   DECID — where DECID is some decimal number — references the window
1477           with the decimal X11 window id DECID.
1478

OBJECTS

1480           Warning
1481           The object tree is not stable yet, i.e. its interface may change
1482           until the next stable release. So check this documentation again
1483           after upgrading the next time.
1484
1485       The object tree is a collection of objects with attributes similar to
1486       /sys known from the Linux kernel. Many entities (like tags, monitors,
1487       clients, ...) have objects to access their attributes directly. The
1488       tree is printed by the object_tree command and looks more or less as
1489       follows:
1490
1491           $ herbstclient object_tree
1492           ╾─┐
1493             ├─┐ tags
1494             │ ├─┐ by-name
1495             │ │ ├─╼ 1
1496             │ │ ...
1497             │ │ └─╼ 9
1498             │ └─╼ focus
1499             ├─┐ clients
1500             │ ├─╼ 0x1400022
1501             │ └─╼ focus
1502             └─┐ monitors
1503               ├─╼ by-name
1504               └─╼ focus
1505
1506       To print a subtree starting at a certain object, pass the PATH of the
1507       object to object_tree. The object PATH is the path using the separator
1508       . (dot), e.g. tags.by-name:
1509
1510           $ herbstclient object_tree tags.by-name.
1511           ╾─┐ tags.by-name.
1512             ├─╼ 1
1513             ├─╼ 2
1514             ...
1515             └─╼ 9
1516
1517       To query all attributes and children of a object, pass its PATH to
1518       attr:
1519
1520           $ herbstclient attr tags.
1521           2 children:
1522             by-name.
1523             focus.
1524
1525           1 attributes:
1526            .---- type
1527            | .-- writeable
1528            V V
1529            u - count                = 9
1530
1531           $ herbstclient attr tags.focus.
1532           0 children.
1533           6 attributes:
1534            .---- type
1535            | .-- writeable
1536            V V
1537            s w name                 = "1"
1538            b w floating             = false
1539            i - frame_count          = 2
1540            i - client_count         = 1
1541            i - curframe_windex      = 0
1542            i - curframe_wcount      = 1
1543
1544       This already gives an intuition of the output: attr first lists the
1545       names of the child objects and then all attributes, telling for each
1546       attribute:
1547
1548       ·   its type
1549
1550           ·   b for boolean
1551
1552           ·   c for color
1553
1554           ·   i for integer
1555
1556           ·   r for regex
1557
1558           ·   s for string
1559
1560           ·   u for unsigned integer
1561
1562       ·   if it is writeable by the user: w if yes, - else.
1563
1564       ·   the name of the attribute
1565
1566       ·   its current value (only quoted for strings)
1567
1568       To get the unquoted value of a certain attribute, address the attribute
1569       using the same syntax as for object paths and pass it to attr or
1570       get_attr:
1571
1572           $ herbstclient attr clients.focus.title
1573           herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1574           $ herbstclient get_attr  clients.focus.title
1575           herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1576
1577       To change a writeable attribute value pass the new value to attr or to
1578       set_attr:
1579
1580           $ herbstclient attr tags.focus.floating
1581           false
1582           $ herbstclient attr tags.focus.floating true
1583           $ herbstclient attr tags.focus.floating
1584           true
1585           $ herbstclient set_attr tags.focus.floating false
1586           $ herbstclient attr tags.focus.floating
1587           false
1588
1589       Just look around to get a feeling what is there. The detailed tree
1590       content is listed as follows:
1591
1592       ·   tags: subtree for tags.
1593
1594           ┌──────────┬────────────────┐
1595           │u - count │ number of tags │
1596           └──────────┴────────────────┘
1597
1598           ·   index: the object of the tag with index index.
1599
1600           ·   by-name
1601
1602               ·   TAG: an object for each tag with the name TAG
1603
1604                   ┌────────────────────┬────────────────────────────┐
1605                   │s w name            │ name of the tag            │
1606                   ├────────────────────┼────────────────────────────┤
1607                   │b w floating        │ if it is in floating mode  │
1608                   ├────────────────────┼────────────────────────────┤
1609                   │i - index           │ index of this tag          │
1610                   ├────────────────────┼────────────────────────────┤
1611                   │i - frame_count     │ number of frames           │
1612                   ├────────────────────┼────────────────────────────┤
1613                   │i - client_count    │ number of clients on this  │
1614                   │                    │ tag                        │
1615                   ├────────────────────┼────────────────────────────┤
1616                   │i - urgent_count    │ number of urgent clients   │
1617                   │                    │ on this tag                │
1618                   ├────────────────────┼────────────────────────────┤
1619                   │i - curframe_windex │ index of the focused       │
1620                   │                    │ client in the select frame │
1621                   ├────────────────────┼────────────────────────────┤
1622                   │i - curframe_wcount │ number of clients in the   │
1623                   │                    │ selected frame             │
1624                   └────────────────────┴────────────────────────────┘
1625
1626           ·   focus: the object of the focused tag
1627
1628       ·   clients
1629
1630           ·   WINID: a object for each client with its WINID
1631
1632               ┌───────────────────────┬────────────────────────────┐
1633               │s - winid              │ its window id              │
1634               ├───────────────────────┼────────────────────────────┤
1635               │s - title              │ its window title           │
1636               ├───────────────────────┼────────────────────────────┤
1637               │r - keymask            │ A regular expression that  │
1638               │                       │ is matched against the     │
1639               │                       │ string representation of   │
1640               │                       │ all key bindings (as they  │
1641               │                       │ are printed by             │
1642               │                       │ list_keybinds). While this │
1643               │                       │ client is focused, only    │
1644               │                       │ bindings that match the    │
1645               │                       │ expression will be active. │
1646               │                       │ Any other bindings will be │
1647               │                       │ disabled. The default      │
1648               │                       │ keymask is an empty string │
1649               │                       │ (""), which does not       │
1650               │                       │ disable any keybinding.    │
1651               ├───────────────────────┼────────────────────────────┤
1652               │r - keys_inactive      │ A regular expression that  │
1653               │                       │ describes which            │
1654               │                       │ keybindings are inactive   │
1655               │                       │ while the client is        │
1656               │                       │ focused. If a key          │
1657               │                       │ combination is pressed and │
1658               │                       │ its string representation  │
1659               │                       │ (as given by               │
1660               │                       │ list_keybinds) matches the │
1661               │                       │ regex, then the key press  │
1662               │                       │ is propagated to the       │
1663               │                       │ client.                    │
1664               ├───────────────────────┼────────────────────────────┤
1665               │s - tag                │ the tag it’s currently on  │
1666               ├───────────────────────┼────────────────────────────┤
1667               │i - pid                │ the process id of it (-1   │
1668               │                       │ if unset)                  │
1669               ├───────────────────────┼────────────────────────────┤
1670               │s - class              │ the class of it (second    │
1671               │                       │ entry in WM_CLASS)         │
1672               ├───────────────────────┼────────────────────────────┤
1673               │s - instance           │ the instance of it (first  │
1674               │                       │ entry in WM_CLASS)         │
1675               ├───────────────────────┼────────────────────────────┤
1676               │b w fullscreen         │                            │
1677               ├───────────────────────┼────────────────────────────┤
1678               │b w floating           │ whether this client is in  │
1679               │                       │ floating mode              │
1680               ├───────────────────────┼────────────────────────────┤
1681               │b w pseudotile         │                            │
1682               ├───────────────────────┼────────────────────────────┤
1683               │b w ewmhrequests       │ if ewmh requests are       │
1684               │                       │ permitted for this client  │
1685               ├───────────────────────┼────────────────────────────┤
1686               │b w ewmhnotify         │ if the client is told      │
1687               │                       │ about its state via ewmh   │
1688               ├───────────────────────┼────────────────────────────┤
1689               │b w urgent             │ its urgent state           │
1690               ├───────────────────────┼────────────────────────────┤
1691               │b w sizehints_tiling   │ if sizehints for this      │
1692               │                       │ client should be respected │
1693               │                       │ in tiling mode             │
1694               ├───────────────────────┼────────────────────────────┤
1695               │b w sizehints_floating │ if sizehints for this      │
1696               │                       │ client should be respected │
1697               │                       │ in floating mode           │
1698               └───────────────────────┴────────────────────────────┘
1699
1700           ·   focus: the object of the focused client, if any
1701
1702           ·   dragged: the object of a client which is dragged by the mouse,
1703               if any. See the documentation of the mousebind command for
1704               examples.
1705
1706       ·   monitors
1707
1708           ┌──────────┬────────────────────┐
1709           │u - count │ number of monitors │
1710           └──────────┴────────────────────┘
1711
1712           ·   INDEX: a object for each monitor with its INDEX
1713
1714           ·   by-name
1715
1716               ·   NAME: a object for each named monitor
1717
1718                   ┌─────────────┬──────────────────────────┐
1719                   │s - name     │ its name                 │
1720                   ├─────────────┼──────────────────────────┤
1721                   │i - index    │ its index                │
1722                   ├─────────────┼──────────────────────────┤
1723                   │s - tag      │ the tag currently viewed │
1724                   │             │ on it                    │
1725                   ├─────────────┼──────────────────────────┤
1726                   │b - lock_tag │                          │
1727                   └─────────────┴──────────────────────────┘
1728
1729           ·   focus: the object of the focused monitor
1730
1731       ·   settings has an attribute for each setting. See SETTINGS for a
1732           list.
1733
1734       ·   theme has attributes to configure the window decorations.  theme
1735           and many of its child objects have the following attributes
1736
1737           ┌─────────────────────┬────────────────────────────┐
1738           │i w border_width     │ the base width of the      │
1739           │                     │ border                     │
1740           ├─────────────────────┼────────────────────────────┤
1741           │i w padding_top      │ additional border width on │
1742           │                     │ the top                    │
1743           ├─────────────────────┼────────────────────────────┤
1744           │i w padding_right    │ on the right               │
1745           ├─────────────────────┼────────────────────────────┤
1746           │i w padding_bottom   │ on the bottom              │
1747           ├─────────────────────┼────────────────────────────┤
1748           │i w padding_left     │ and on the left of the     │
1749           │                     │ border                     │
1750           ├─────────────────────┼────────────────────────────┤
1751           │c w color            │ the basic background color │
1752           │                     │ of the border              │
1753           ├─────────────────────┼────────────────────────────┤
1754           │i w inner_width      │ width of the border around │
1755           │                     │ the clients content        │
1756           ├─────────────────────┼────────────────────────────┤
1757           │c w inner_color      │ its color                  │
1758           ├─────────────────────┼────────────────────────────┤
1759           │i w outer_width      │ width of an additional     │
1760           │                     │ border close to the edge   │
1761           ├─────────────────────┼────────────────────────────┤
1762           │c w outer_color      │ its color                  │
1763           ├─────────────────────┼────────────────────────────┤
1764           │c w background_color │ color behind window        │
1765           │                     │ contents visible on resize │
1766           ├─────────────────────┼────────────────────────────┤
1767           │b w tight_decoration │ specifies whether the size │
1768           │                     │ hints also affect the      │
1769           │                     │ window decoration or only  │
1770           │                     │ the window contents of     │
1771           │                     │ tiled clients (requires    │
1772           │                     │ enabled sizehints_tiling)  │
1773           ├─────────────────────┼────────────────────────────┤
1774           │s w reset            │ Writing this resets all    │
1775           │                     │ attributes to a default    │
1776           │                     │ value                      │
1777           └─────────────────────┴────────────────────────────┘
1778
1779               inner_color/inner_width
1780                     ╻        outer_color/outer_width
1781                     │                  ╻
1782                     │                  │
1783               ┌────╴│╶─────────────────┷─────┐ ╮ border_width
1784               │     │      color             │ ┝     +
1785               │  ┌──┷─────────────────────┐  │ ╯ padding_top
1786               │  │====================....│  │
1787               │  │== window content ==....│  │
1788               │  │====================..╾──────── background_color
1789               │  │........................│  │
1790               │  └────────────────────────┘  │ ⎱ border_width +
1791               └──────────────────────────────┘ ⎰ padding_bottom
1792
1793           Setting an attribute of the theme object just propagates the value
1794           to the respective attribute of the tiling and the floating object.
1795
1796           ·   tiling configures the decoration of tiled clients, setting one
1797               of its attributes propagates the respective attribute of the
1798               active, normal and urgent child objects.
1799
1800               ·   active configures the decoration of focused and tiled
1801                   clients
1802
1803               ·   normal configures the decoration of unfocused and tiled
1804                   clients
1805
1806               ·   urgent configures the decoration of urgent and tiled
1807                   clients
1808
1809           ·   floating behaves analogously to tiling
1810
1811           ·   minimal behaves analogously to tiling and configures those
1812               minimal decorations triggered by smart_window_surroundings.
1813
1814           ·   active propagates the attribute values to tiling.active and
1815               floating.active
1816
1817           ·   normal propagates the attribute values to tiling.normal and
1818               floating.normal
1819
1820           ·   urgent propagates the attribute values to tiling.urgent and
1821               floating.urgent
1822

AUTOSTART FILE

1824       There is no configuration file but an autostart file, which is executed
1825       on startup. It is also executed on command reload. If not specified by
1826       the --autostart argument, autostart file is located at
1827       $XDG_CONFIG_HOME/herbstluftwm/autostart or at
1828       ~/.config/herbstluftwm/autostart. Normally it consists of a few
1829       herbstclient calls. If executing the autostart file in a user’s home
1830       fails the global autostart file (mostly placed at
1831       /etc/xdg/herbstluftwm/autostart) is executed as a fallback.
1832
1833       For a quick install, copy the default autostart file to
1834       ~/.config/herbstluftwm/.
1835

HOOKS

1837       On special events, herbstluftwm emits some hooks (with parameters). You
1838       can receive or wait for them with herbstclient(1). Also custom hooks
1839       can be emitted with the emit_hook command. The following hooks are
1840       emitted by herbstluftwm itself:
1841
1842       fullscreen [on|off] WINID
1843           The fullscreen state of window WINID was changed to [on|off].
1844
1845       tag_changed TAG MONITOR
1846           The tag TAG was selected on MONITOR.
1847
1848       focus_changed WINID TITLE
1849           The window WINID was focused. Its window title is TITLE.
1850
1851       window_title_changed WINID TITLE
1852           The title of the focused window was changed. Its window id is WINID
1853           and its new title is TITLE.
1854
1855       tag_flags
1856           The flags (i.e. urgent or filled state) have been changed.
1857
1858       tag_added TAG
1859           A tag named TAG was added.
1860
1861       tag_removed TAG
1862           The tag named TAG was removed.
1863
1864       tag_renamed OLD NEW
1865           The tag name changed from OLD to NEW.
1866
1867       urgent [on|off] WINID
1868           The urgent state of client with given WINID has been changed to
1869           [on|off].
1870
1871       rule NAME WINID
1872           A window with the id WINID appeared which triggered a rule with the
1873           consequence hook=NAME.
1874
1875       There are also other useful hooks, which never will be emitted by
1876       herbstluftwm itself, but which can be emitted with the emit_hook
1877       command:
1878
1879       quit_panel
1880           Tells a panel to quit. The default panel.sh quits on this hook.
1881           Many scripts are using this hook.
1882
1883       reload
1884           Tells all daemons that the autostart file is reloaded — and tells
1885           them to quit. This hook should be emitted in the first line of
1886           every autostart file.
1887

STACKING

1889       Every tag has its own stack of clients that are on this tag. Similar to
1890       the EWMH specification each tag stack contains several layers, which
1891       are from top to bottom:
1892
1893       ·   the focused client (if raise_on_focus_temporarily is enabled)
1894
1895       ·   clients in fullscreen
1896
1897       ·   normal clients
1898
1899       ·   frame decorations
1900
1901       All monitors are managed in one large stack which only consists of the
1902       stacks of the visible tags put above each other. The stacking order of
1903       these monitors is independent from their indices and can be modified
1904       using the raise_monitor command. The current stack is illustrated by
1905       the stack command.
1906

EWMH

1908       As far as possible, herbstluftwm tries to be EWMH compliant. That
1909       includes:
1910
1911       ·   Information about tag names and client lists is provided.
1912
1913       ·   Desktop windows from desktop environments are not managed and kept
1914           below the other windows.
1915
1916       ·   Client requests like getting focused are only processed if the
1917           setting focus_stealing_prevention is disabled.
1918

ENVIRONMENT VARIABLES

1920       DISPLAY
1921           Specifies the DISPLAY to use.
1922

FILES

1924       The following files are used by herbstluftwm:
1925
1926       ·   autostart, see section AUTOSTART FILE.
1927

EXIT STATUS

1929       Returns 0 on success. Returns EXIT_FAILURE if it cannot startup or if
1930       wmexec fails.
1931

BUGS

1933       See the herbstluftwm distribution BUGS file.
1934

COMMUNITY

1936       Feel free to join the IRC channel #herbstluftwm on irc.freenode.net.
1937

AUTHOR

1939       herbstluftwm was written by Thorsten Wißmann. All contributors are
1940       listed in the herbstluftwm distribution AUTHORS file.
1941

RESOURCES

1943       Homepage: http://herbstluftwm.org
1944
1945       Github page: http://github.com/herbstluftwm/herbstluftwm
1946
1947       Patch submission and bug reporting:
1948
1949           hlwm@lists.herbstluftwm.org
1950

COPYING

1952       Copyright 2011-2020 Thorsten Wißmann. All rights reserved.
1953
1954       This software is licensed under the "Simplified BSD License". See
1955       LICENSE for details.
1956
1957
1958
1959  herbstluftwm 0.9.0              2020-12-07                   HERBSTLUFTWM(1)
Impressum