i3-msg

Run an i3 command

$ i3-msg [command]

$ i3-msg -t get_workspaces

$ i3-msg -t get_tree

i3-msg [-h|--help] [-c configfile] [-d|--disable-emergency-restart] [-s socket] [-q|--quiet] [-t|--type TYPE] [-v|--version] [cmd ...]

-c, --config CONFIGFILE
    Use specified config file instead of default (~/.config/i3/config)

-d, --disable-emergency-restart
    Prevent i3 emergency restart on SIGTERM

-h, --help
    Display help message and exit

-q, --quiet
    Suppress output for successful commands

-s, --socket SOCKET
    Override default IPC socket path (/run/user/$UID/i3/ipc-socket.$DISPLAY)

-t, --type TYPE
    Reply type: json, get_json, subscribe, send_json

-v, --version
    Print version information and exit

i3-msg is a utility for the i3 tiling window manager that enables sending commands to i3 over its IPC socket. It allows scripting and automation of window management tasks, such as switching workspaces, moving windows, executing applications, or querying i3 state.

Typically used in shell scripts, i3-msg communicates with the running i3 instance by sending JSON-formatted IPC messages. Commands mirror those in i3's config file, like workspace 2 or exec firefox. Without arguments, it reads commands from stdin, making it suitable for piping.

Key features include customizable socket paths, config files, reply types (json, get_json, etc.), and quiet mode. It's essential for integrating i3 with other tools, status bars like i3bar, or dynamic configurations. Requires i3 version 4.2+ for full IPC support.

Requires running i3 instance with IPC enabled; socket permissions must allow access (user/group). No command given reads from stdin. Errors if i3 unresponsive.

json: Full JSON event. get_json: Single JSON line. subscribe: Stream events. send_json: Raw JSON send.

i3-msg workspace 1
i3-msg -t get_json '[class="firefox"]' | jq
echo 'reload' | i3-msg -q

Part of i3wm since version 4.0 (2012), IPC introduced in 4.2. Developed by Michael Stapelberg; evolved with JSON IPC for scripting. Widely used in i3 ecosystem for automation.

i3(1), i3bar(1), i3-sensible(1), i3ipc(7)