I3-MATCH(1) i3-match Manual I3-MATCH(1)
NAME
i3-match - match and query i3/sway window properties and events
SYNOPSIS
i3-match [-S] [option|filter]... [-o field...]
swaymatch [-S] [option|filter]... [-o field...]
DESCRIPTION
i3-match provides command-line access to i3 window manager's IPC inter‐
face. Also works with sway(1); See SWAY MODE below and sway-ipc(7).
i3-match has two modes of operation: match-mode and subscribe-mode. In
both modes, filters are used to select nodes.
Match-mode is the default, where nodes are containers/windows in the
tree.
The -S option enables subscribe-mode, where i3-match listens for events
via the subscribe IPC feature. Each event is matched as a node. See
also the -m option.
OPTIONS
-W Enable sway mode. Default when invoked as swaymatch. Overrides
a previous -I option. See SWAY MODE below.
-I Disable sway mode. See SWAY MODE below. Overrides a previous -W
option.
-a Print unmatched nodes too. Output the :match field or specify -h
to highlight matches. If specified twice in subscribe mode
("almost all"), events not matching filters for the :evtype
field are left out.
-d delimiter
Set the delimiter. Default is space (" ").
-e field op value
Specify a filter with three following arguments. See FILTERS be‐
low.
-h Highlight matches. Useful with -a.
-i file
Read json tree from file instead of querying via i3 IPC. If file
is a single dash ("-") read from stdin. Match-mode only.
-l num Consider success after num matches. Default is 1. Match-mode
only (see also -n).
-m Keep monitoring for events infinitely. Specifying -n after this
option overrides this effect. Sets printed fields to :evtype
change current/name container/name binding/command payload in‐
put/identifier id unless -o is given. Subscribe-mode only.
-n num In match-mode: Exit after printing num nodes. If no output
fields are selected, this option is ignored (you may want -l in‐
stead). In subscribe-mode: exit after matching num nodes.
-o field...
Print the values of given fields for each matched node. Printed
values are separated by the delimiter (see -d). All arguments
following this option are treated as field names.
-S Enter subscribe-mode. This may not be specified after mode-spe‐
cific options.
-s path
Specify the path of the i3 socket to use. By default, uses the
socket of the i3 instance of the current display.
-t Same as -o :itree name. If both -t and -o are given, :itree is
added before the first specified output field. Match-mode only.
FILTERS
Filters are conditions applied to each node to choose which nodes to
select. All filters need to match to a node for it to be selected.
Filters are specified with the syntax field op value in a single argu‐
ment without delimiting characters or by specifying the arguments -e
field op value. field is the name of any field (see FIELDS below).
value is the string to match against. op is one of the following oper‐
ators:
= Matches when the value of field is exactly value.
*= Matches when the value of field contains value.
^= Matches when the value of field starts with value.
$= Matches when the value of field ends with value.
The meaning of any operator can be inverted by prefixing it with an ex‐
clamation mark ("!").
FIELDS
Fields contain values for each node. They are accessed via their names
in the json-structure of each node.
Hierarchies of json objects are accessed using slashes ("/") as separa‐
tor.
Fields not found for a node are empty. There is no check for whether a
field name is valid.
See i3 IPC documentation (https://i3wm.org/docs/ipc.html) and the
EVENTS section in sway-ipc(7) for a list of fields.
Pseudo fields
i3-match provides additional information for each node. Pseudo-fields
access this information. All pseudo-fields start with colon (":").
:match 1, if this node is a match. 0 otherwise. 0 when used in a fil‐
ter.
:level Nesting level of this node in i3's layout tree. 0 for the root
node. 0 in subscribe-mode.
:floating
1, if this node is contained in a floating_nodes array. Incre‐
ments by 1 for each nesting level inside such a node. 0 in sub‐
scribe-mode.
:scratch
1, if this node's scratchpad_state is not none. Increments by 1
for each nesting level inside such a node. 0 in subscribe-mode.
:workspace
Name of the workspace containing this node. Empty if this node
is not contained by a workspace. Empty in subscribe-mode.
:output
Name of the output (screen) containing this node. Empty if this
node is not contained by an output. Empty in subscribe-mode.
:sibi Index of this node within the current list of siblings. 0 in
subscribe-mode.
:sibc Number of siblings of this node. 0 in subscribe-mode.
:childc
Number of children of this node. 0 in subscribe-mode.
:indent
Outputs an indented hierarchy tree. Matched nodes are indented
with two dashes ("--") other nodes with two spaces (" ") per
level. Only useful in match-mode.
:itree Outputs an indented hierarchy resembling the output of tree(1).
Only useful in match-mode.
:evtype
Event type in subscribe-mode. One of workspace, output, mode,
window, barconfig_update, binding, shutdown, tick.
In sway mode, one of workspace, mode, window, barconfig_update,
binding, shutdown, tick, bar_state_update, input.
This field is special when used in filters in subscribe-mode:
Filters on this field are used to decide which events to sub‐
scribe for. This is an optimization and only makes a visual dif‐
ference when specifying -a twice.
If filters are specified such that no event types match,
i3-match exits with an error message.
none in match-mode.
:nodei Index of this node.
:matchc
Number of matches up to this point. This is incremented after a
node is matched and before processing output.
:json Json representation of this node formatted without newlines.
:json:field
Json representation of field formatted without newlines. See
FIELDS above for field. Pseudo fields are not available here.
ENVIRONMENT VARIABLES
I3SOCK If not in sway mode and -s is not given, this variable is used
to determine the path of i3's IPC socket, overriding the usual
lookup.
SWAYSOCK
If set to a non-empty value and the -I option is not specified,
sway mode is enabled.
In sway mode, this variable is used instead of I3SOCK. See SWAY
MODE blow.
EXIT STATUS
The exit status is 0 on success, 1 if success condition was not met and
2 if an error occurred. In match-mode success means that at least one
node was selected. If -l was specified, the exit status is according to
that option. In subscribe-mode i3-match exits on success, so the exit
status is always 0 unless an error occurred.
SWAY MODE
If the -W option is enabled, or the program is invoked as swaymatch, or
the SWAYSOCK environment variable is set to a non-empty string, sway
mode is enabled unless the -I option is in effect. Sway mode enables
full compatibility with the sway(1) compositor.
Sway mode has the following effects:
The set of events in subscribe mode is changed to those supported
by sway(1). See the :evtype FIELD above. See also the SUBSCRIBE
message and EVENTS section in sway-ipc(7).
The SWAYSOCK environment variable is used to find the socket path
instead of I3SOCK. See ENVIRONMENT VARIABLES above.
The command sway --get-socketpath is used instead of i3 --get-sock‐
etpath as the last resort method to find the socket path. Note that
since sway also uses the SWAYSOCK environment variable, this will
likely fail, as of sway version 1.7.
EXAMPLES
i3-match -t
Print a simple hierarchy tree with names for each container.
i3-match 'name*=Firefox' -l 2 && echo true
Print "true" when there are at least two containers with titles
containing "Firefox".
i3-match focused=true -a -h -o :itree rect/{width,height} name
Print width, height and title for each window and container.
Highlight the focused window.
i3-match focused=true -ahto rect/{width,height} name
Same as above.
i3-match -S :evtype=window change=new
Wait for a window to be created, then exit.
i3-match -Sm :evtype=window container/focused=true -o container/name
Print the name of the focused window every time it changes.
SEE ALSO
i3(1) sway(1) sway-ipc(7)
i3-match 2022-05-11 I3-MATCH(1)