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
              input/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
              subscribe-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.

              To  detect scratch windows on sway(1), containers with ids found
              in the focus array of the __i3_scratch workspace are  also  con‐
              sidered scratch windows.

       :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,   output,   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-socketpath 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                          2024-03-02                       I3-MATCH(1)