FreeBSD Manual Pages
ICESH(1) User Commands ICESH(1)
NAME
icesh - control window properties and the IceWM window manager
SYNOPSIS
icesh OPTIONS|ACTIONS+
DESCRIPTION
icesh provides two types of commands:
1. Commands to directly interact with icewm:
These are listed in the section "MANAGER ACTIONS" below. They are easy
to use, because they don't require to select one or more windows. For
example, "icesh restart" will restart icewm and "icesh clients" lists
the applications that are managed by icewm.
2. Commands that operate on a selection of windows:
See the section "WINDOW ACTIONS" below. For example, "icesh close" is a
request to close a window, but which window? Now icesh will turn the
mouse pointer into a crosshair. Click on a window and a close request
will be sent to that application.
The power of icesh lies in its ability to programmatically select one
or more windows and operate on that selection. This can be used in
scripts and in icewm-keys(5) to define your own window management
hotkeys. For example, to immediately close all xterm windows do "icesh
-c xterm close".
There are a dozen "SELECT OPTIONS" to select windows. They start with
a '-' or a '+'. The '-' starts a new selection, while the '+' adds
more windows to an existing selection.
This selection of windows can be reduced by "FILTER OPTIONS". These
remove unwanted windows from the current selection. Multiple filter
options can be given. For example, "icesh -c xterm -W this close" will
close only those xterms that are shown on the current workspace. The
xterms on other workspaces are filtered out by the "-W this" filter op-
tion.
There is no limit to the number of commands, selections, filters and ac-
tions that you can give to a single icesh command. They are processed and
evaluated one by one from left to right. This makes icesh a small declara-
tive programming language. Have a look at some examples near the end of
this document.
OPTIONS
icesh recognizes the following options:
SELECT OPTIONS
Select options specify the window or windows to which subsequent actions
apply. If none is given, but an action does require a window, then a selec-
tion crosshair is shown to select the desired window interactively. The
manager actions do not require window options.
The following options select one or more client windows. If needed, they
can be repeated for successive actions.
-a, -all
Selects all client windows of the window manager.
-f, -focus, +f, +focus
Selects the application window that is currently focused. The option
with minus sign replaces the existing selection with the focused win-
dow. With a plus sign the focused window is added to an existing selec-
tion.
+g, +group
Extend the current selection with client windows that belong to the
same application window group.
-r, -root, +r, +root
Selects the root window. The option with minus sign replaces the ex-
isting selection with the root window. With a plus sign the root window
is added to an existing selection.
-s, -shown
Selects all client windows that are on the current workspace.
-t, -top
Selects all toplevel windows from the display unconditionally. This
includes windows that have never been mapped and windows with the over-
ride redirect bit set to evade management.
-w, -window, +w, +window WINDOW_ID
Specifies the identifier of the window, WINDOW_ID, for which the action
applies. Special identifiers are root for the root window and focus
for the currently focused window. The option with minus sign replaces
the existing selection. With a plus sign the window is added to an ex-
isting selection.
-x, -xembed
Selects all windows that are embedded using the XEMBED protocol.
+c, +class CLASS
Extend the current selection with client windows that have a WM_CLASS
property equal to CLASS. This is the resource instance and class name.
If CLASS contains a period, only windows with exactly the same WM_CLASS
property are matched. If there is no period, windows of the same class
and windows of the same instance are selected.
+C, +Class
Extend the current selection with client windows that have a WM_CLASS
property similar to the already selected set of windows.
-D, -Dockapps
Selects all Dockapp applications that are managed by icewm.
+P, +Pid
Extend the current selection with client windows that have the same
process identifier as one of the selected windows.
-T Selects the IceWM taskbar.
-A, -Await
Wait for one or more new client windows to appear and make that the new
selection.
FILTER OPTIONS
The following options filter the currently selected set of windows. If no
previous select option was given then a -all option is implicitly assumed
to filter all client windows.
-c, -class CLASS
Filters the set of windows on their WM_CLASS property. This is the re-
source instance and class name. If CLASS contains a period, only win-
dows with exactly the same WM_CLASS property are matched. If there is
no period, windows of the same class and windows of the same instance
(aka. -name) are selected.
-l, -last
Filter clients and keep only the most recent client.
-m, -machine HOST
Filters clients by host name. Clients with a WM_CLIENT_MACHINE property
equal to HOST are selected.
-n, -name NAME
Filters clients by _NET_WM_NAME or WM_NAME. NAME matches any part of
the property value. To match at the beginning use a "^" prefix. To
match at the end use a "$" suffix.
-p, -pid PID
Filters clients by process ID. Clients are selected that have a process
ID of PID, when libXRes is at version 1.2, or that have a _NET_WM_PID
property equal to PID.
-u, -unmapped
Filter clients and keep those that are currently not viewable. These
are hidden, minimized, rolled-up, or on another workspace.
-v, -viewable
Filter clients and keep only those that are currently viewable. These
clients are mapped on the current workspace.
-k, -kovered
Filter clients and keep only those that are currently viewable and that
are at least partially covered by another viewable window.
-G, -Gravity GRAVITY
Filters clients by the window gravity field of the WM_NORMAL_HINTS
property. Clients with a gravity equal to GRAVITY are selected. If
GRAVITY starts with an exclamation mark then the filtering is inverted.
-L, -Layer LAYER
Filters clients by GNOME window layer, which can either be a layer name
or a layer number. See EXPRESSIONS below. If LAYER starts with an ex-
clamation mark then the filtering is inverted.
-N, -Netstate STATE
Filters clients by EWMH window state. Clients that have at least an
EWMH window state of STATE are selected. This state refers to details
like MINIZED or MAXIMIZED. See EXPRESSIONS below. If STATE starts with
an exclamation mark then the filtering is inverted. A question mark
"?" filters clients with any bit set in STATE.
-P, -Property PROP[=value]
Filters clients by property. Clients that have a property PROP are se-
lected. If the optional value is given, the match succeeds only if PROP
is a string, window, cardinal, or atom, with a value equal to value.
The filtering is inverted if PROP starts with an exclamation mark.
-R, -Role ROLE
Filters clients by WM_WINDOW_ROLE. Clients that have a WM_WINDOW_ROLE
property value equal to ROLE are selected. The filtering is inverted
if ROLE starts with an exclamation mark.
-W, -Workspace WORKSPACE
Filter clients by workspace. Workspace WORKSPACE is either a workspace
name, or a workspace number counting from zero, or the word "this" for
the current workspace, or the word "All" for all workspaces. If WORK-
SPACE starts with an exclamation mark then the filtering is inverted.
-X, -Xinerama MONITOR
Limit clients by RandR/Xinerama monitor. Only operate on clients that
are displayed on MONITOR, where MONITOR can be "All" for all monitors,
"this" for the monitor where the active window is displayed, or a moni-
tor number starting from zero. See the output of "randr" or "xinerama"
below.
-Z, -Zerminal
Keep only terminals: clients that have forked a shell.
GENERAL OPTIONS
The following options are identical for every IceWM command.
-d, -display DISPLAY
Specifies the X11 DISPLAY. If unspecified, defaults to $DISPLAY.
-h, --help
Print a brief usage statement to stdout and exit.
-V, --version
Print the program version to stdout and exit.
-C, --copying
Print copying permissions to stdout for the program and exit.
-q, --quiet
Don't complain if no matching windows could be found.
ACTIONS
icesh expects one or more action arguments. There are two kinds of ac-
tions: window actions and manager actions. The first operates on the se-
lected windows. The second directly interacts with the icewm window man-
ager.
WINDOW ACTIONS
The following actions affect the selected window or windows.
activate
Activate the window, aka. to focus.
close
Send a close request to the client that created the window.
killForce an immediate close down of the client that created the window.
id Print window identifiers for the selected windows.
pid Print process identifiers for the selected windows.
listShow window details, like geometry and names.
lower
Lower the window.
raise
Raise the window.
above
Stack the window above others.
below
Stack the window below others.
rollup
Rollup the specified window.
fullscreen
Set the window to fullscreen.
maximize
Maximize the window.
horizontal
Maximize the window only horizontally.
vertical
Maximize the window only vertically.
minimize
Minimize the window.
restore
Restore the window to normal and clear urgency.
hideHide the window.
unhide
Reveal the window.
skipDon't show the window on the taskbar.
unskip
Do show the window on the taskbar.
sticky
Show the window on all workspaces.
unsticky
Show the window on just one workspace.
urgent
Set the urgency flag to flash the task button.
resize WIDTH HEIGHT
Resize window to WIDTH by HEIGHT window units. For text based applica-
tions like terminals, a window unit is the size of a single character
cell.
sizeto WIDTH HEIGHT
Resize window to WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends with a
percent sign "%", then they refer to a percentage of the desktop work
area. For instance, "sizeto 50% 100%" resizes to half the desktop width
and whatever height is available above or below the taskbar.
sizeby WIDTH HEIGHT
Resize window by WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends with a
percent sign "%", then they refer to a percentage of the current window
size. For instance, "sizeby 50% 200" increases the width by 50% and in-
creases the height by 200 pixels.
move X Y
Move the selected window or windows to the screen position X Y. To
specify X or Y values relative to the right side or bottom side precede
the value with an extra minus sign, like in "move -+10 --20". When X
or Y end with a percent sign "%", they refer to a percentage of the
desktop work area.
moveby X Y
Displace window by X Y pixels.
center
Position the window in the center of the desktop work area.
leftPosition the window against the left side of the desktop work area.
right
Position the window against the right side of the desktop work area.
top Position the window against the top side of the desktop work area.
bottom
Position the window against the bottom side of the desktop work area.
setIconTitle TITLE
Set the icon title to TITLE.
getIconTitle
Print the icon title.
setWindowTitle TITLE
Set the window title to TITLE.
getWindowTitle
Print the window title.
setGeometry GEOMETRY
Set the window geometry to GEOMETRY. This geometry should be specified
in a format that can be parsed by XParseGeometry(3). Negative offsets
are with respect to the bottom or right side of the screen. Use "+-"
for a truly negative position.
getGeometry
Print the window geometry.
setClass CLASS
Set the resource name and class to CLASS, which should be a resource
name and a resource class connected by a dot. To preserve either the
existing name or class, use a percentage sign for that part.
getClass
Print the resource name and class.
netState [STATE]
If STATE is omitted then it shows the EWMH window state. If STATE
starts with a "+" then flags in STATE are appended to the existing EWMH
window state. If STATE starts with a "-" then flags in STATE are re-
moved from the existing EWMH window state. If STATE starts with a "^"
then flags in STATE are toggled with respect to the existing EWMH win-
dow state. If STATE starts with a "=" then the EWMH window state is
set to STATE. See EXPRESSIONS below. A list of EWMH flags can be found
in the output of "icesh symbols".
setLayer LAYER
Move the specified window to another window layer. See EXPRESSIONS be-
low for a list of LAYER symbols.
getLayer
Print the window layer for the specified window.
setWorkspace WORKSPACE
Move the specified window to another workspace. Select the root window
to change the current workspace. If WORKSPACE is "All" then the speci-
fied window becomes visible on all workspaces. Specify "this" for the
current workspace, "next" for the subsequent workspace or "prev" for
the preceding workspace.
getWorkspace
Print the workspace for the specified window.
opacity [OPACITY]
Print the window opacity if OPACITY is not given, otherwise set the
window opacity to OPACITY.
setTrayOption TRAYOPTION
Set the IceWM tray option for the specified window to TRAYOPTION. See
IceWM tray options, below, for TRAYOPTION symbols.
getTrayOption
Print the IceWM tray option for the specified window.
setNormalGravity GRAVITY
Set the window gravity field in the WM_NORMAL_HINTS property for the
specified window to GRAVITY. See below for GRAVITY symbols.
getNormalGravity
Print the window gravity from the WM_NORMAL_HINTS property for the
specified window.
setWindowGravity GRAVITY
Set the window gravity for the specified window to GRAVITY. See below
for GRAVITY symbols.
getWindowGravity
Print the window gravity for the specified window.
setBitGravity GRAVITY
Set the bit gravity> for the specified window to GRAVITY. See below
for GRAVITY symbols.
getBitGravity
Print the bit gravity for the specified window.
motif [funcs FUNCTIONS | decor DECORATIONS | remove]
Query, set or modify the "_MOTIF_WM_HINTS" property for the specified
window. Without arguments motif will show the current value, but only
if the window has such a property. The property can be removed or reset
with the remove argument. With funcs and decor individual fields of
this property can be enabled or disabled. If FUNCTIONS or DECORATIONS
starts with a minus or plus sign then the existing value is modified,
otherwise it is set to the new value. Note that if "All" is set, other
set fields are disabled and cleared fields are enabled.
borderless
Hide the frame borders and title.
bordered
Show the frame borders and title.
denormal
Remove the WM_NORMAL_HINTS property, if it exists. This lifts
font-size restrictions on resizing, especially for terminals.
prop PROPERTY
Print the value of property PROPERTY, if it is present.
properties
Print all properties and their values.
frame
Print the identifier of the window frame.
extents
Print the window identifier and the frame border sizes: left, right,
top and bottom.
focusmodel
Print the ICCCM focus model as advertised by the client window. This
is either Locally, Passive, Globally or NoInput.
override [0|1]
Print the override redirect status for the window, or if either 0 or 1
is given, then disable or enable the override redirect status.
tabto label
Move the windows as tabs to a frame that has "frame" label label. Such
a frame is created if needed.
untab
Move each window to its own frame, if it is currently tabbed.
loadicon image.pam
Load an icon from file, which must be in the PAM image format, with di-
mensions at most 256, a depth of 4, and type RGB_ALPHA.
saveicon file000.pam
Save an icon to a new file in the PAM image format. Digits are in-
creased to generate a unique new filename for each window. The window
must have a _NET_WM_ICON property.
usertime
Show the time of last user interaction in milliseconds.
click window-x window-y button
Send a button press and release event at position (window-x, window-y).
A negative position is relative to the bottom right corner. The mouse
pointer is warped to the position before sending the events. The button
number should be between 1 and 5 inclusive.
monitors top bottom left right
This sets the monitors to use for fullscreen. Top, bottom, left, and
right are indices of the icesh xinerama command.
spy Observe the selected windows and report any changes. This includes fo-
cus, visibility, position, size and all window properties. To monitor
all of the protocol request messages that client applications may send
to icewm, also spy on the root window.
stacking
Sort the list of windows from topmost to bottom-most.
reverse
Reverse the order of the list of windows.
switchmenu
Output the list as a menu for icewm's QuickSwitch. This action is to be
used in a switchkey directive in the "keys" file.
print format
For each window in the selection, print a line according to format.
Here common backslash-escapes are recognized as well as the following
percent formatting options:
% A literal percent sign.
h The window height.
w The window width.
x The window x-position.
y The window y-position.
g The window geometry.
i The window identifying handle.
o An icon name.
p The process-ID of the window application.
c The WM_CLASS property of the window.
m The WM_CLIENT_MACHINE property of the window.
t The window title.
W The current workspace of the window.
Each percent format option may start with a minus sign for left-align-
ment and have a numeric field width.
MANAGER ACTIONS
The following actions control the IceWM window manager and therefore do not
require a window select or filter option:
listWorkspaces
List the names of all workspaces.
current
Show the number and name of the current workspace.
goto WORKSPACE
Change the current workspace to WORKSPACE. Specify "next" for the sub-
sequent workspace or "prev" for the preceding workspace.
workspaces [COUNT]
Print the number of workspaces if COUNT is not given, otherwise set the
number of workspaces to COUNT.
getWorkspaceName INDEX
Print the name of workspace INDEX, where INDEX is a workspace number
starting from zero.
getWorkspaceNames
Print the name of all workspaces, one per line of output.
setWorkspaceName INDEX NAME
Change the name of the workspace INDEX to NAME, where INDEX is a work-
space number starting from zero.
setWorkspaceNames NAME [NAME]*
Change the workspace names to the list of NAMEs.
addWorkspace NAME
Create a new workspace with name NAME.
desktop [SHOWING]
If SHOWING is 1 then set "showing the desktop" mode. If SHOWING is 0
then turn off "showing the desktop". Print the current mode if SHOWING
is not given.
workarea
Print the dimensions of the work area for the current workspace. This
is the desktop, but minus space occupied by dock and panel windows.
randr
Summarize the RandR configuration.
xinerama
Summarize the Xinerama configuration.
check
Print information about the current window manager, like name, version,
class, locale, command, host name and pid.
clients
List all managed client windows, their titles and geometries.
shown
List all mapped client windows for the current desktop, their titles
and geometries.
windows
List all toplevel windows, their titles and geometries.
systray
List applications that are managed by the IceWM system tray.
xembed
List application windows that are embedded using the XEMBED protocol.
This is another way to discover system tray applications.
logout
Let icewm execute the "LogoutCommand".
reboot
Let icewm execute the "RebootCommand".
shutdown
Let icewm execute the "ShutdownCommand".
cancel
Let icewm cancel the logout/reboot/shutdown.
about
Let icewm show the about window.
windowlist
Let icewm show the window list window.
restart
Let icewm restart itself.
suspend
Let icewm execute the "SuspendCommand".
hibernate
Let icewm execute the "HibernateCommand".
winoptions
Let icewm reload the "winoptions". This only affects new windows.
keysLet icewm reload the "keys" file.
toolbar
Let icewm reload the "toolbar" file.
refresh
Let icewm refresh the desktop background.
guievents
Monitor the ICEWM_GUI_EVENT property and report all changes. Hit
"Ctrl+C" to abort this and continue with the next command.
delay [time]
Stop execution for time or 0.1 seconds.
runonce program [arguments...]
This action is meant to be used together with the -class option. Only
if no window is matched by WM_CLASS then program [arguments...] is exe-
cuted.
loop [count]
Loop back to the beginning of the command and repeat. The optional
count limits the number of repetitions.
pickChoose a window by a mouse button click.
x11time
Show the current X11 server time in milliseconds.
syncSynchronize with the IceWM window manager. That is, wait for icewm to
process all previous actions.
symbols
List all named symbols.
CONDITIONALS
Icesh supports "if-then-else" expressions. The full syntax is:
if selection
then
actions
elif selection
then
actions
else
actions
end
Where "selection" is a sequence of selection and filtering options, which
evaluates to true when it is non-empty. That is, if one or more windows
fulfilled the condition. If it is empty, then its "actions" clause is ig-
nored and the subsequent "elif" or "else" clause is tried or taken. Each
clause is optional.
Whenever a selection condition evaluates to false, the window selection
that existed before the "if" clause is immediately restored. This also
happens after an "end" clause.
EXPRESSIONS
Some of the window actions require one or two EXPRESSION arguments.
EXPRESSION ::= SYMBOL | EXPRESSION { "+" | "|" | "-" } SYMBOL
This says that an expression is either a SYMBOL or an expression which is
combined with an operator to a SYMBOL. In other words, an expression is a
sequence of symbols, which are combined using operators, where an operator
may be a plus, a vertical bar or a minus.
Each SYMBOL may be either a number or a named symbol from one of the fol-
lowing applicable domains, depending upon the context in which it is used:
Window layer
Named symbols of the domain Window layer (numeric range: 0-15):
Desktop (0)
Below (2)
Normal (4)
OnTop (6)
Dock (8)
AboveDock (10)
Menu (12)
Fullscreen (14)
AboveAll (15)
These symbols are used with the LAYER argument to the "setLayer" ac-
tion.
IceWM tray option
Named symbols of the domain IceWM tray option (numeric range: 0-2):
Ignore (0)
Minimized (1)
Exclusive (2)
These symbols are used with the TRAYOPTION argument to the "setTrayOp-
tion" action.
Gravity symbols
Named symbols for window and bit gravity (numeric range: 0-10):
ForgetGravity (0)
NorthWestGravity (1)
NorthGravity (2)
NorthEastGravity (3)
WestGravity (4)
CenterGravity (5)
EastGravity (6)
SouthWestGravity (7)
SouthGravity (8)
SouthEastGravity (9)
StaticGravity (10)
Motif functions
All (1)
Resize (2)
Move (4)
Minimize (8)
Maximize (16)
Close (32)
Motif decorations
All (1)
Border (2)
Resize (4)
Title (8)
Menu (16)
Minimize (32)
Maximize (64)
EWMH window state symbols
Named symbols of the domain EWMH state (numeric range: 0-8191):
ABOVE (1)
BELOW (2)
DEMANDS_ATTENTION (4)
FOCUSED (8)
FULLSCREEN (16)
HIDDEN (32)
MAXIMIZED_HORZ (64)
MAXIMIZED_VERT (128)
MODAL (256)
SHADED (512)
SKIP_PAGER (1024)
SKIP_TASKBAR (2048)
STICKY (4096)
EXAMPLES
List all workspace names:
icesh listWorkspaces
Example output:
workspace #0: `main'
workspace #1: `web'
workspace #2: `doc'
workspace #3: `dev'
Close terminal work and activate terminal fun.
icesh -c work.XTerm close -a -c fun.XTerm activate
Print opacity for all xterms.
icesh -c XTerm opacity
Change opacity for all xterms.
icesh -c XTerm opacity 84
Move all windows on workspace "Top" to the current workspace.
icesh -W "Top" setWorkspace "this"
Restore all hidden clients, minimize all clients on the current workspace
and activate Firefox.
icesh -N HIDDEN restore -a -W "this" minimize -a -c Firefox activate
Resize the focused window to occupy the right half of the desktop area.
icesh -f sizeto 49% 100% top right raise
Toggle the frame border of the focused window.
if icesh -f motif | grep -q 'decor:$'; then \
icesh -f motif decor All; else icesh -f motif decor ""; fi
Here is a different solution using conditionals.
icesh -f if -P _NET_FRAME_EXTENTS=0 then bordered else borderless
Here is a conditional to either toggle the visibility of a roxterm that has
a WM_WINDOW_ROLE value of "special" or start it with runonce.
icesh if -c roxterm.Roxterm -R special then \
if -v then hide \
elif -u then setWorkspace this activate end \
else runonce roxterm --role=special
Collect all urxvt terminals from the fourth workspace in a single frame on
the current workspace.
icesh -W 3 -c urxvt tabto myfunnyname
Use the loop construct conditionally to wait for a certain window to ap-
pear.
icesh -t if -n Tooltip then list else delay 0.05 loop end
ENVIRONMENT
DISPLAY
The default display.
EXIT STATUS
0 The last action completed successfully.
1 The last action completed unsuccessfully, or no window met the condi-
tion.
2 A conditional has invalid syntax.
3 The display could not be opened.
4 The X server reports an error while processing a request.
COMPLIANCE
icesh is largely compliant with the EWMH and ICCCM specifications. Some
commands, like manager actions, are specific to IceWM.
SEE ALSO
icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1), XParseGeometry(3).
BUGS
Please report bugs at <https://github.com/ice-wm/icewm/issues>.
AUTHOR
Brian Bidulock <mailto:bidulock@openss7.org>.
See --copying for full copyright notice and copying permissions.
LICENSE
IceWM is licensed under the GNU Library General Public License. See the
COPYING file in the distribution or use the --copying flag to display copy-
ing permissions.
icewm 4.0.0 2026-01-01 ICESH(1)
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=icesh&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>