herbstluftwm is controlled by internal commands, which can be executed
via herbstclient(1) or via keybindings.
Executes the autostart file.
Prints the version of the running herbstluftwm
echo [ARGS ...]
Prints all given ARGS separated by a single space
and a newline afterwards.
Ignores all arguments and always returns success, i.e.
Ignores all arguments and always returns failure, i.e.
Lists all available commands.
List currently configured monitors with their index, area
(as rectangle), name (if named) and currently viewed tag.
Lists all active rules. Each line consists of all the
parameters the rule was called with, plus its label, separated by tabs.
Lists all bound keys with their associated command. Each
line consists of one key combination and the command with its parameters
separated by tabs.
Tabs within command parameters are not escaped!
Increases the monitors_locked setting. Use this if
you want to do multiple window actions at once (i.e. without repainting
between the single steps). See also: unlock
Decreases the monitors_locked setting. If
monitors_locked is changed to 0, then all monitors are repainted again.
See also: lock
keybind KEY COMMAND [ARGS ...]
Adds a key binding. When KEY
is pressed, the
(with its ARGS
) is executed. A key binding is a
(possibly empty) list of modifiers (Mod1, Mod2, Mod3, Mod4, Mod5, Alt, Super,
Control/Ctrl, Shift) and one key (see keysymdef.h for a list of keys).
Modifiers and the key are concatenated with -
If there is already a binding for this KEY
, it will be overwritten.
•keybind Mod4+Ctrl+q quit
•keybind Mod1-i toggle always_show_frame
•keybind Mod1-Shift-space cycle_layout -1
Removes the key binding for KEY. The syntax for
KEY is defined in keybind. If -F or --all is
given, then all key bindings will be removed.
mousebind BUTTON ACTION [COMMAND ...]
Adds a mouse binding for the floating mode. When
is pressed, the specified ACTION
will be performed.
has a similar syntax to the KEY
argument of keybind: It
consists of a list of modifiers (separated by -
modifiers are listed in the description of keybind
) and exactly one
•B1 or Button1
•B2 or Button2
•B3 or Button3
•B4 or Button4
•B5 or Button5
must be one of the following actions:
•move: Moves the window by dragging the
•resize: Resizes the window by dragging a
•zoom: Resizes the window into all four directions
while keeping the center of the window constant.
•call: Only calls the specified COMMAND
while client.dragged links to the client on which the BUTTON has been
While an ACTION
is performed, client.dragged is
the client which is dragged. E.g.:
•mousebind Mod1-Button3 zoom
•mousebind Mod1-B4 call substitute WID
clients.dragged.winid spawn transset-df --inc -i WID 0.05
•mousebind Mod1-B5 call substitute WID
clients.dragged.winid spawn transset-df --dec -i WID -m 0.2 0.05
Removes all mouse bindings.
spawn EXECUTABLE [ARGS ...]
Spawns an EXECUTABLE
with its ARGS
details see man 3 execvp
•spawn xterm -e man 3 execvp
wmexec [WINDOWMANAGER [ARGS ...]]
Executes the WINDOWMANAGER
with its ARGS
This is useful to switch the window manager in the running session without
restarting the session. If no or an invalid WINDOWMANAGER
then herbstluftwm is restarted. For details see man 3 execvp
chain SEPARATOR [COMMANDS ...]
chain expects a SEPARATOR
and a list of
with arguments. The commands have to be separated by the
. The SEPARATOR
can by any word and only is
recognized as the separator between commands if it exactly matches
. "chain" outputs the appended outputs of all
commands and returns the exit code of the last executed command. Examples are:
•Create a tag called "foo" and directly
chain , add foo , use foo
•Rotate the layout clockwise:
chain .-. lock .-. rotate .-. rotate .-. rotate .-. unlock
•This will only create a tag called
chain , add foo, use foo
•Separator "." defined, but
"," is used:
chain . add foo , use foo
and SEPARATOR [COMMANDS ...]
"and" behaves like the chain command but only
executes the specified COMMANDS while the commands return the exit code
or SEPARATOR [COMMANDS ...]
"or" behaves like the chain command but only
executes the specified COMMANDS until one command returns the exit code
"!" executes the provided command, but inverts
its return value. If the provided command returns a nonzero, "!"
returns a 0, if the command returns a zero, "!" returns a 1.
"try" executes the provided command, prints its
output, but always returns success, i.e. 0.
"silent" executes the provided command, but
discards its output and only returns its exit code.
Focuses the nth window in a frame. The first window has
INDEX 0. If INDEX is negative or greater than the last window
index, then the last window is focused.
Cycles the selection within the current frame by
DELTA. If DELTA is omitted, DELTA = 1 will be used.
DELTA can be negative; DELTA = -1 means: cycle in the opposite
direction by 1.
cycle_all [--skip-invisible] [DIRECTION]
Cycles through all windows and frames on the current tag.
DIRECTION = 1 means forward, DIRECTION = -1 means backward,
DIRECTION = 0 has no effect. DIRECTION defaults to 1. If there
are multiple windows within on frame, then it acts similar to the cycle
command. (The cycle_all command focuses the next/previous leaf in the
layout tree.). If --skip-invisible is given, then this only
cycles through all visible windows and skips invisible windows in the max
layout. The focused window is raised.
Cycles through all frames on the current tag.
DIRECTION = 1 means forward, DIRECTION = -1 means backward,
DIRECTION = 0 has no effect. DIRECTION defaults to 1.
cycle_layout [DELTA [LAYOUTS ...]]
Cycles the layout algorithm in the current frame by
defaults to 1. You can find a list of layout
algorithms above. If a list of LAYOUTS
is given, cycle_layout will
cycle through those instead of the default layout algorithm list. This is done
by finding the first occurrence of the current layout in LAYOUTS
picking the next layout according to DELTA
. If the current layout
doesn’t occur in LAYOUTS
, the first entry is picked. Example:
•cycle_layout 1 vertical grid
Sets the layout algorithm in the current frame to
LAYOUT. For the list of layouts, check the list of layout algorithms
Closes the specified window gracefully or the focused
window if none is given explicitly. See the section on WINDOW IDS how to
reference a certain window.
Closes the focused window or removes the current frame if
no window is focused.
Closes the focused window and removes the current frame
if no other window is present in that frame.
split ALIGN [FRACTION]
Splits the focused frame into two subframes with a
between 0 and 1 which defaults to 0.5. ALIGN
is one of
•bottom (= vertical)
•right (= horizontal)
(split along longest side)
It specifies which of the two halves will be empty after the
split. The other half will be occupied by the currently focused frame. After
splitting, the originally focuse frame will stay focused. One special
ALIGN mode is explode, which splits the frame in such a way
that the window sizes and positions are kept as much as possible. If no
FRACTION is given to explode mode an optimal fraction is
picked automatically. Example:
•split bottom 0.5
•split horiz 0.3
•split vertical 0.5
focus [-i|-e] DIRECTION
Moves the focus from current frame to the next frame or
client in DIRECTION
which is in:
(internal) is given or
default_direction_external_only is unset, then the next client in
can also be within the same frame. If there is no client
within this frame or -e
(external) is given, then the next frame in
will be focused.
The direction between frames is defined as follows: The focus is
in a leaf of the binary tree. Each inner node in the tree remembers the last
focus direction (child 0 or child 1). The algorithm uses the shortest
possible way from the leaf (the currently focused frame) to the root until
it is possible to change focus in the specified DIRECTION. From there
the focus goes back to the leaf.
Example: The focus is at frame A. After executing focus
right focus will be at frame C.
Tree: V,0 Screen: ┌─────┐┌─────┐ (before)
╱ ╲ │ B ││ C │
╱ ╲ └─────┘└─────┘
H,1 H,0 ┌─────┐┌─────┐
╱ ╲ ╱ ╲ │ A* ││ D │
A* B C D └─────┘└─────┘
Tree: V,0 Screen: ┌─────┐┌─────┐ (after focus right)
╱ ╲ │ B ││ C* │
╱ ╲ └─────┘└─────┘
H,1 H,0 ┌─────┐┌─────┐
╱ ╲ ╱ ╲ │ A ││ D │
A B C* D └─────┘└─────┘
If the currently focused client is floated, then the next
floating window in the specified direction is focused and raised.
If focus_crosses_monitor_boundaries is set and no
client or frame is found in the specified DIRECTION, then the next
monitor in that DIRECTION is focused.
focus_edge [-i|-e] DIRECTION
Focuses the window on the edge of the tag in the
. The DIRECTIONS
specified at the focus
If -i (internal) is given or
default_direction_external_only is unset, then the window on the edge of the
tag will be focused. Else, only the frame on the edge of the tag will be
focused, and the window that was last focused in that frame will be
Raises the specified window. See the section on WINDOW
IDS on how to reference a certain window. Its result is only visible in
The WINID also can specify an unmanaged window, although
the completion for the raise command does not list the IDs of unmanaged
Puts the focus to the specified window. See the section
on WINDOW IDS on how to reference a certain window.
Moves the specified window to the current frame and
focuses it. See the section on WINDOW IDS on how to reference a certain
resize DIRECTION FRACTIONDELTA
Changes the next fraction in specified DIRECTION
behaves as specified at the
command. You should not omit the sign -
because in future versions, the behaviour may change if the sign is omitted.
•resize right +0.05
•resize down -0.1
shift_edge [-i|-e] DIRECTION
Shifts the focused window to the the edge of a tag in the
specified DIRECTION. The DIRECTIONS behave as specified at the
focus command and -i and -e behave as specified at the
shift [-i|-e] DIRECTION
Shifts the focused window to the next frame in the
specified DIRECTION. The DIRECTIONS and -i|-e
behave as specified at the focus command. If the focused client is
floated instead of being tiled, then client is shifted to the next window or
Moves the focused window to the tag on the specified
MONITOR. See the MONITORS section, how to address a monitor.
Removes focused frame and merges its windows to its
Rotates the layout on the focused tag counterclockwise by
90 degrees. This only manipulates the alignment of frames, not the content of
set NAME VALUE
Sets the specified setting NAME to VALUE.
All SETTINGS are listed in the section below.
Prints the value of setting NAME. All
SETTINGS are listed in the section below.
Toggles the setting NAME if it’s an integer
setting: If its value is unequal to 0, it becomes 0; else its previous value
(which was unequal to 0) is restored.
cycle_value NAME VALUES ...
Cycles value of the setting NAME
: I.e. it searches the first occurrence of the current value in
and changes the value to the next in the list or to the first
one if the end is reached or current value wasn’t found. Example:
•cycle_value frame_gap 0 5 10 15
•cycle_value frame_bg_normal_color red green
Cycles monitor focused by DELTA. DELTA
defaults to 1.
Puts focus to the specified monitor. See the MONITORS
section, how to address a monitor.
Creates a new empty tag named TAG.
Switches the focused monitor to specified
use_index INDEX [--skip-visible]
Switches the focused monitor to the TAG
. If INDEX
starts with + or -, then INDEX
is treated relative to the current TAG
. If --skip-visible
passed and INDEX
is relative, then tags that are already visible on a
monitor are skipped. E.g. this cycles backwards through the tags:
•use_index -1 --skip-visible
Switches the focused monitor to the previously viewed
merge_tag TAG [TARGET]
Removes tag named TAG and moves all its windows to
tag TARGET. If TARGET is omitted, the focused tag will be
rename OLDTAG NEWTAG
Renames tag named OLDTAG to NEWTAG.
Moves the focused window to the tag named
move_index INDEX [--skip-visible]
Moves the focused window to the tag specified by
INDEX. Analogical to the argument for use_index: If INDEX
starts with + or -, then it is treated relative. If --skip-visible is
passed with a relative index, then already visible tags are skipped.
Lock the tag switching on the specified monitor. If no
argument is given, the currently focused monitor is used. When the tag
switching is disabled for a monitor, the commands use and
use_index have no effect when executed there. When
swap_monitors_to_get_tag is enabled, switching to a tag which is
located on a locked monitor, switches to that monitor instead of stealing it
from there. The lock state of a monitor is indicated by "[LOCKED]"
in the list_monitors output.
Re-enables the tag switching on the specified monitor. If
no argument is given, the currently focused monitor is used. This is the
reverse operation to lock_tag and has no further side effects but
removing this lock.
disjoin_rects RECTS ...
Takes a list of rectangles and splits them into smaller
pieces until all rectangles are disjoint, the result rectangles are printed
line by line. This command does not modify the current list of monitors! So
this can be useful in combination with the set_monitors command.
•E.g. disjoin_rects 600x400+0+0 600x400+300+250
•In the above example two monitors are split into
5 monitors, which graphically means:
│ │ └──────┘
│ ┌───┼───┐ ┌─┐┌───┐┌──┐
│ │ │ │ disjoin │ ││ ││ │
└──┼───┘ │ ─────────> └─┘└───┘└──┘
│ │ ┌───────┐
set_monitors RECTS ...
Sets the list of monitors exactly
to the list of
•The i’th existing monitor is moved to the
i’th given RECT
•New monitors are created if there are more
RECTS then monitors
•Existing monitors are deleted if there are more
monitors then RECTS
Sets the list of monitors to the available Xinerama
monitors. If the Xinerama extension is missing, it will fall back to one
monitor across the entire screen. If the detected monitors overlap, the will
be split into more monitors that are disjoint but cover the same area using
If -l or --list is passed, the list of rectangles of
detected pyhsical monitors is printed. So hc detect_monitors is equivalent
to the bash command hc set_monitors $(hc disjoin_rects $(hc detect_monitors
add_monitor RECT [TAG [NAME]]
Adds a monitor on the specified rectangle RECT
on it. TAG
currently must not be displayed on any
other monitor. RECT
is a string of the form
. If no or an empty TAG
is given, then any
free tag will be chosen. If a NAME
is given, you can reference to this
monitor by its name instead of using an index. Example:
•add_monitor 1024x768-20+0 mynewtag main
Removes the specified monitor.
move_monitor MONITOR RECT [PADUP
[PADRIGHT [PADDOWN [PADLEFT]]]]
Moves the specified monitor to rectangle RECT.
RECT is defined as in add_monitor. If no or an empty pad is
given, it is not changed.
Raises the specified monitor or the current one if
MONITOR is omitted.
rename_monitor MONITOR NAME
(Re)names an already existing monitor. If NAME is
empty, it removes the monitor’s name.
Prints the stack of monitors with the visible tags and
their layers as a tree. The order of the printed stack is top to bottom. The
style is configured by the tree_style setting.
monitor_rect [[-p] MONITOR]
Prints the rectangle of the specified monitor in the
format: X Y W H If no MONITOR or cur is given, then the
current monitor is used. If -p is supplied, then the remaining rect
without the pad around this monitor is printed.
pad MONITOR [PADUP [PADRIGHT [PADDOWN
Sets the pad of specified monitor to the specified
padding. If no or an empty padding is given, it is not changed.
Lists the padding of the specified monitor, or the
currently focused monitor if no monitor is given.
layout [TAG [INDEX]]
Prints the layout of frame with INDEX
, in a nice tree style. Its style is defined by the
setting. If no TAG
is given, the current tag is used.
If no INDEX
is given, the root frame is used. To specify INDEX
without specifying TAG
(i.e. use current tag), pass an empty string as
An example output is:
╾─┐ horizontal 50% selection=1
├─╼ vertical: 0xe00009
└─┐ vertical 50% selection=0
├─╼ vertical: 0xa00009 [FOCUS]
└─╼ vertical: 0x1000009
dump [TAG [INDEX]]
Prints the same information as the layout
but in a machine readable format. Its output can be read back with the
An example output (formatted afterwards) is:
(clients vertical:0 0xe00009)
(clients vertical:0 0xa00009)
(clients vertical:0 0x1000009)))
load [TAG] LAYOUT
Loads a given LAYOUT description to specified
TAG or current tag if no TAG is given.
LAYOUT is exactly one parameter. If you are calling it
manually from your shell or from a script, quote it properly!
complete POSITION [COMMAND ARGS ...]
Prints the result of tab completion for the partial
with optional ARGS
. You usually do not need this,
because there is already tab completion for bash. Example:
•complete 0 m
prints all commands beginning with m
•complete 1 toggle fra
prints all settings beginning with fra that can be toggled
complete_shell POSITION [COMMAND ARGS
Behaves like complete
with the following extras,
useful for completion on posix shells:
•Escape sequences are removed in COMMAND
•A space is appended to each full completion
•Special characters will be escaped in the
emit_hook ARGS ...
Emits a custom hook to all idling herbstclients.
Print a tab separated list of all tags for the specified
index. If no MONITOR
index is given, the focused monitor
is used. Each tag name is prefixed with one char, which indicates its state:
•. the tag is empty
•: the tag is not empty
•+ the tag is viewed on the specified
MONITOR, but this monitor is not focused.
•# the tag is viewed on the specified
MONITOR and it is focused.
•- the tag is viewed on a different
MONITOR, but this monitor is not focused.
•% the tag is viewed on a different
MONITOR and it is focused.
•! the tag contains an urgent window
If you use a tab in one of the tag names, then tag_status is
probably quite useless for you.
Changes the current tag to floating/tiling mode on
specified TAG or prints it current status. If no TAG is given,
the current tag is used. If no argument is given, floating mode is toggled. If
status is given, then on or off is printed, depending of
the floating state of TAG.
Defines a rule which will be applied to all new clients.
Its behaviour is described in the RULES section.
Removes all rules named LABEL. If --all or -F is
passed, then all rules are removed.
Sets or toggles the fullscreen state of the focused
client. If no argument is given, fullscreen mode is toggled.
Sets or toggles the pseudotile state of the focused
client. If a client is pseudotiled, then in tiling mode the client is only
moved but not resized - the client size will stay the floating size. The only
reason to resize the client is to ensure that it fits into its tile. If no
argument is given, pseudotile mode is toggled.
Prints the tree of objects. If the object path
PATH is given, only the subtree starting at PATH is printed. See
the OBJECTS section for more details.
attr [PATH [NEWVALUE]
Prints the children and attributes of the given object
addressed by PATH. If PATH is an attribute, then print the
attribute value. If NEWVALUE is given, assign NEWVALUE to the
attribute given by PATH. See the OBJECTS section for more
Print the value of the specified ATTRIBUTE as
described in the OBJECTS section.
set_attr ATTRIBUTE NEWVALUE
Assign NEWVALUE to the specified ATTRIBUTE
as described in the OBJECTS section.
Creates a new attribute with the name and in the object
specified by PATH. Its type is specified by the first argument. The
attribute name has to begin with my_.
Removes the user defined attribute PATH.
substitute IDENTIFIER ATTRIBUTE COMMAND
Replaces all exact occurrences of IDENTIFIER
and its ARGS
by the value of the ATTRIBUTE
that the COMMAND
also is replaced by the attribute value if it equals
. The replaced command with its arguments then is executed.
•substitute MYTITLE clients.focus.title echo
Prints the title of the currently focused window.
sprintf IDENTIFIER FORMAT [ATTRIBUTES ...]
COMMAND [ARGS ...]
Replaces all exact occurrences of IDENTIFIER
and its ARGS
by the string specified by FORMAT
Each %s in FORMAT
stands for the value of the next attribute in
, similar to the printf(1)
command. The replaced
command with its arguments then is executed. Examples:
•sprintf STR title=%s clients.focus.title echo STR
Prints the title of the currently focused window prepended by
•sprintf X tag=%s tags.focus.name rule once X
Moves the next client that appears to the tag that is currently
•sprintf X %s/%s tags.focus.index tags.count echo
Tells which tag is focused and how many tags there are
•sprintf l somelongstring echo l l l
Prints somelongstring three times, separated by spaces.
IDENTIFIER COMMAND [ARGS ...]
Creates a temporary attribute with the given type and
replaces all occurrences of IDENTIFIER in COMMAND and
ARGS by by the path of the temporary attribute. The replaced command
with its arguments is executed then. The exit status of COMMAND is
compare ATTRIBUTE OPERATOR VALUE
Compares the value of ATTRIBUTE
using the comparation method OPERATOR
. If the comparation succeeds, it
returns 0, else 1. The operators are:
•=: ATTRIBUTE's value equals
•!=: ATTRIBUTE's value does not
•le: ATTRIBUTE's value <=
•lt: ATTRIBUTE's value <
•ge: ATTRIBUTE's value >=
•gt: ATTRIBUTE's value >
can only be used if ATTRIBUTE
is of the type integer or unsigned integer. Note that the first parameter must
always be an attribute and the second a constant value. If you want to compare
two attributes, use the substitute command:
substitute FC tags.focus.frame_count \
compare tags.focus.client_count gt FC
It returns success if there are more clients on the focused tag
Gets the value of the environment variable
setenv NAME VALUE
Set the value of the environment variable NAME to
Unsets the environment variable NAME.
Settings configure the behaviour of herbstluftwm and can be controlled via the
set, get and toggle commands. There are two types of
settings: Strings and integer values. An integer value is set, if its value is
1 or another value unequal to 0. An integer value is unset, if its value is 0.
The gap between frames in the tiling mode.
The padding within a frame in the tiling mode, i.e. the
space between the border of a frame and the windows within it.
The gap between windows within one frame in the tiling
If a client is dragged in floating mode, then it snaps to
neighbour clients if the distance between them is smaller then
Specifies the remaining gap if a dragged client snaps to
an edge in floating mode. If snap_gap is set to 0, no gap will remain.
Specifies the gap around a monitor. If the monitor is
selected and the mouse position would be restored into this gap, it is set to
the center of the monitor. This is useful, when the monitor was left via mouse
movement, but is reselected by keyboard. If the gap is 0 (default), the mouse
is never recentered.
The border color of a focused frame.
The border color of an unfocused frame.
The color of the inner border of a frame.
The fill color of a focused frame.
The fill color of an unfocused frame (It is only visible
if always_show_frame is set).
If set, the background of frames are transparent. That
means a rectangle is cut out frome the inner such that only the frame border
and a stripe of width frame_transparent_width can be seen. Use
frame_active_opacity and frame_normal_opacity for real
Specifies the width of the remaining frame colored with
frame_bg_active_color if frame_bg_transparent is set.
Border width of a frame.
The width of the inner border of a frame. Must be less
than frame_border_width, since it does not add to the frame border width but
is a part of it.
If set, the focus command crosses monitor boundaries. If
there is no client in the direction given to focus, then the monitor in the
specified direction is focused.
If set, a window is raised if it is focused. The value of
this setting is only used in floating mode.
If set, a window is raised temporarily if it is focused
on its tag. Temporarily in this case means that the window will return to its
previous stacking position if another window is focused.
If set, a window is raised if it is clicked. The value of
this setting is only noticed in floating mode.
Border width of a window.
The width of the inner border of a window. Must be less
than window_border_width, since it does not add to the window border width but
is a part of it.
Border color of a focused window.
Border color of an unfocused window.
Border color of an unfocused but urgent window.
Color of the inner border of a window.
If set, all frames are displayed. If unset, only frames
with focus or with windows in it are displayed.
Focused frame opacity in percent. Requires a running
compositing manager to take actual effect.
Unfocused frame opacity in percent. Requires a running
compositing manager to take actual effect.
Index of the frame layout, which is used if a new frame
is created (by split or on a new tag). For a list of valid indices and their
meanings, check the list of layout algorithms above.
This setting controls the behaviour of focus and shift if
no -e or -i argument is given. if set, then focus and shift
changes the focused frame even if there are other clients in this frame in the
specified DIRECTION. Else, a client within current frame is selected if
it is in the specified DIRECTION.
This setting affects the size of the last client in a
frame that is arranged by grid layout. If set, then the last client always
fills the gap within this frame. If unset, then the last client has the same
size as all other clients in this frame.
If set, frame borders and gaps will be removed when
there’s no ambiguity regarding the focused frame.
If set, window borders and gaps will be removed and
minimal when there’s no ambiguity regarding the focused window. This
minimal window decoration can be configured by the theme.minimal object.
If set and a window is focused by mouse cursor, this
window is focused (this feature is also known as sloppy focus). If unset, you
need to click to change the window focus by mouse.
If another window is hidden by the focus change (e.g. when having
pseudotiled windows in the max layout) then an extra click is required to
change the focus.
If set, only pagers and taskbars are allowed to change
the focus. If unset, all applications can request a focus change.
If greater than 0, then the clients on all monitors
aren’t moved or resized anymore. If it is set to 0, then the arranging
of monitors is enabled again, and all monitors are rearranged if their content
has changed in the meantime. You should not change this setting manually due
to concurrency issues; use the commands lock and unlock
If set: If you want to view a tag, that already is viewed
on another monitor, then the monitor contents will be swapped and you see the
wanted tag on the focused monitor. If not set, the other monitor is focused if
it shows the desired tag.
If set, detect_monitors is automatically executed every
time a monitor is connected, disconnected or resized.
It contains the chars that are used to print a nice ascii
tree. It must contain at least 8 characters. e.g. X|:#+*-. produces a tree
#-. child 0
| #-* child 01
| +-* child 02
+-. child 1
: #-* child 10
: +-* child 01
Useful values for tree_style are: ╾│
├└╼─┐ or -| |'--. or ╾│
It controls the value of the _NET_WM_NAME property on the
root window, which specifies the name of the running window manager. The value
of this setting is not updated if the actual _NET_WM_NAME property on the root
window is changed externally. Example usage:
•cycle_value wmname herbstluftwm LG3D
If greater than 0, it specifies the least distance
between a centered pseudotile window and the border of the frame or tile it is
assigned to. If this distance is lower than
pseudotile_center_threshold, it is aligned to the top left of the
If set, a client’s window content is resized
immediately during resizing it with the mouse. If unset, the client’s
content is resized after the mouse button are released.
If set, verbose output is logged to herbstluftwm’s
stderr. The default value is controlled by the --verbose command line
Rules are used to change default properties for certain clients when they
appear. Each rule matches against a certain subset of all clients and defines
a set of properties for them (called CONSEQUENCEs). A rule can be
defined with this command:
Each rule consists of a list of FLAGs, CONDITIONs,
CONSEQUENCEs and, optionally, a LABEL. (each of them can be
optionally prefixed with two dashes (--) to provide a more
Each rule can be given a custom label by specifying the
If multiple labels are specified, the last one in the list will be
applied. If no label is given, then the rule will be given an integer name
that represents the index of the rule since the last unrule -F
command (which is triggered in the default autostart).
Rule labels default to an incremental index. These default labels
are unique, unless you assign a different rule a custom integer
LABEL. Default labels can be captured with the printlabel
If a new client appears, herbstluftwm tries to apply each rule to
this new client as follows: If each CONDITION of this rule matches
against this client, then every CONSEQUENCE is executed. (If there
are no conditions given, then this rule is executed for each client)
Each CONDITION consists of a property name, an
operator and a value. Valid operators are:
•~ matches if client’s property is
matched by the regex value.
•= matches if client’s properly
string is equal to value.
Valid properties are:
the first entry in client’s WM_CLASS.
the second entry in client’s WM_CLASS.
client’s window title.
the client’s process id (Warning: the pid is not
available for every client. This only matches if the client sets _NET_WM_PID
to the pid itself).
matches if the age of the rule measured in seconds does
not exceed value. This condition only can be used with the = operator.
If maxage already is exceeded (and never will match again), then this rule is
removed. (With this you can build rules that only live for a certain
matches the _NET_WM_WINDOW_TYPE property of a
matches the WM_WINDOW_ROLE property of a window if it is
set by the window.
Each CONSEQUENCE consists of a NAME=VALUE
pair. Valid NAMES are:
moves the client to tag VALUE.
moves the client to the tag on monitor VALUE. If
the tag consequence was also specified, and switchtag is set for the client,
move the client to that tag, then display that tag on monitor VALUE. If
the tag consequence was specified, but switchtag was not, ignore this
decides whether the client gets the input focus on his
tag. The default is off. VALUE can be on, off or
if focus is activated and the client is put to a not
focused tag, then switchtag tells whether the client’s tag will be
shown or not. If the tag is shown on any monitor but is not focused, the
client’s tag only is brought to the current monitor if
swap_monitors_to_get_tag is activated. VALUE can be on,
off or toggle.
decides whether the client will be managed or not. The
default is on. VALUE can be on, off or
moves the window to a specified index in the tree.
VALUE is a frame index.
sets the pseudotile state of the client. VALUE can
be on, off or toggle.
sets whether the window state (the fullscreen state and
the demands attention flag) can be changed by the application via ewmh itself.
This does not affect the initial fullscreen state requested by the window.
VALUE can be on, off or toggle, it defaults to
sets whether hlwm should let the client know about EMWH
changes (currently only the fullscreen state). If this is set, applications do
not change to their fullscreen-mode while still being fullscreen. VALUE
can be on, off or toggle, it defaults to on.
sets the fullscreen flag of the client. VALUE can
be on, off or toggle.
emits the custom hook rule VALUE WINID when
this rule is triggered by a new window with the id WINID. This
consequence can be used multiple times, which will cause a hook to be emitted
for each occurrence of a hook consequence.
Sets the keymask for an client. A keymask is an regular
expression that is matched against the string represenation (see
list_keybinds). If it matches the keybinding is active when this client is
focused, otherwise it is disabled. The default keymask is an empty string
(""), which does not disable any keybinding.
A rule’s behaviour can be configured by some special
•not: negates the next CONDITION.
•!: same as not.
•once: only apply this rule once (and delete it
•printlabel: prints the label of the newly created
rule to stdout.
•prepend: prepend the rule to the list of rules
instead of appending it. So its consequences may be overwritten by already
•rule --class=Netscape --tag=6 --focus=off
Moves all Netscape instances to tag 6, but doesn’t give
focus to them.
•rule not class~.*[Tt]erm tag=2
Moves all clients to tag 2, if their class does not end with term
•rule class=Thunderbird index=/0
Insert all Thunderbird instances in the tree that has no focus and
there in the first child.
Sets focus to new dialogs which set their _NET_WM_WINDOW_TYPE