i3-ipc man page

i3-ipc -- inter-process communication with i3


i3-ipc [-s] [-t type] [-p] [-j] [-q] [message]


i3-ipc can be used to communicate with i3, the improved tiling window manager, through the provided ipc socket. Useful for scripting the window manager.

Currently implemented message types of i3 are the following:


 The payload of the message is a command for i3
 (like the commands you can bind to keys in the configuration file)
 The command will be executed directly after receiving it.
 The reply will be always {"succes":true} for now.


 Gets the current workspaces.
 The reply will be a JSON-encoded list of workspaces.


 Subscribes your connection to the workspace event.


 Gets the current outputs.
 The reply will be a JSON-encoded list of outputs.


i3-ipc's default mode of operation is to send the command (type 0) specified on the command line.

These options can be used to change this behavior:

-s, --socket

Set the socket file, defaults to ~/.i3/ipc.sock

-t, --type

Set the type. Passing a type of 0 is the default and will send the specified command, type 1 gets the current workspace list, type 2 subscribes to the workspace stream, type 3 gets the current output list.

-p, --pretty-print

This will pretty print the received reply. Useful for the workspace list.

-j, --json

This will print the received reply as raw json-encoded data. Useful to pass to another script.

-q, --quiet

Turn off the output. Useful for command mode.


This is the actual command to send as defined by i3

You may additionally ask for help:

-h, --help

Print help.

-m, --man

Display this man page.


$ i3-ipc -t 1
$ i3-ipc -t 2 -p
$ i3-ipc -t 3 -j
$ i3-ipc "exec xterm"




Jan-Erik Rediger:: badboy@archlinux.us

See Also

i3(1), i3-msg(1), http://i3.zekjur.net/, http://github.com/badboy/i3-ipc


April 2010 badboy i3-ipc Manual