i3-msg

Run an i3 command

$ i3-msg [command]

$ i3-msg -t get_workspaces

$ i3-msg -t get_tree

i3-msg [-s socket] [-t type] [-q] [-v] [-h] [command [arguments]]

<command> [arguments]
    This specifies the i3 command string to be executed by the window manager. Examples include workspace next, move container to scratchpad, exec --no-startup-id firefox, or reload. These commands mirror those found in the i3 configuration file or bound to key combinations.

-s, --socket socket
    Allows you to specify a custom path to the i3 IPC socket. By default, i3-msg automatically discovers the socket path, typically located within the user's runtime directory, e.g., /run/user/<UID>/i3/ipc-socket.<PID> or $XDG_RUNTIME_DIR/i3/ipc-socket.<PID>.

-t, --type type
    Sets the message type for the IPC request. The default type is command for executing i3 actions. Other common types are for querying information, such as get_workspaces, get_outputs, get_tree, get_marks, get_version, get_binding_modes, and get_config.

-q, --quiet
    Suppresses any output from i3-msg. This option is particularly useful when the command is integrated into scripts where no console feedback or success messages are desired, allowing for cleaner script execution.

-v, --version
    Displays the version information for the i3-msg utility and then exits. This helps in verifying the installed version of the tool.

-h, --help
    Shows a comprehensive help message that details the command's usage and lists all available options, then exits. It serves as a quick reference guide for using i3-msg.

The i3-msg command serves as the primary interface for sending commands to a running i3 window manager instance. It establishes communication with i3 through its Inter-Process Communication (IPC) socket, enabling users and scripts to dynamically control various aspects of the desktop environment. This includes managing window layout, navigating and organizing workspaces, executing applications, and querying the current state of the window manager. i3-msg is an essential tool for scripting complex behaviors, configuring custom keybindings beyond what the configuration file directly supports, and for debugging i3 setups. Whether you need to move a window to a specific workspace, toggle its floating state, reload your configuration without restarting i3, or retrieve detailed information about your window tree, i3-msg provides the necessary programmatic access for seamless interaction. It is a fundamental component for extending i3's capabilities and integrating with external tools.

For i3-msg to function, an i3 window manager instance must be actively running; otherwise, the command will fail to establish a connection. Users should exercise caution when sending commands, as incorrect or malformed instructions can lead to unintended alterations in window layout or configuration. Scripts employing i3-msg are advised to include robust error handling. Access to the IPC socket could potentially pose a minor security consideration in multi-user environments if not properly secured, as it grants control over the user's desktop session.

i3-msg communicates with the running i3 daemon through an Inter-Process Communication (IPC) socket. This socket serves as a direct, real-time channel for sending commands and receiving responses. The path to this socket is typically dynamically generated and stored in a user's runtime directory, for instance, $XDG_RUNTIME_DIR/i3/ipc-socket.<PID>, ensuring that each i3 instance has its unique communication endpoint. This robust and efficient IPC mechanism is fundamental to i3's extensibility, allowing third-party tools, custom scripts, and even other applications to deeply integrate and interact with the window manager.

Beyond simply executing direct commands (the default type), i3-msg supports a variety of query message types via the -t option. These queries empower users to retrieve detailed, structured information about the current state of the i3 window manager. For example, i3-msg -t get_tree will return a comprehensive JSON representation of the entire window tree, including all containers, workspaces, and outputs. Similarly, get_workspaces provides data on active workspaces, while get_version retrieves i3's version information. These powerful query capabilities are invaluable for developing custom status bars, monitoring tools, and intelligent scripts that can react dynamically to the window manager's state changes.

The i3-msg utility has been a cornerstone of the i3 window manager project since its inception around 2009. Conceived by Michael Stapelberg as a modern, user-friendly tiling window manager, i3 was designed with a strong emphasis on a simple, well-documented IPC mechanism for programmatic control. i3-msg was developed to provide a straightforward command-line interface to this IPC, enabling users to script complex behaviors, extend their desktop environment's functionality, and interact with i3 outside of standard keybindings. Its consistent and logical design reflects i3's overarching philosophy of providing a highly configurable, scriptable, and transparent environment.

i3(1), i3-config(5), i3-nagbar(1), i3-bar(1), i3-scratchpad(7)