swaymsg

Run a Sway command

$ swaymsg [command]

$ swaymsg [[-t|--type]] get_workspaces

$ swaymsg [[-t|--type]] get_inputs

$ swaymsg [[-t|--type]] get_outputs

$ swaymsg [[-t|--type]] get_tree

swaymsg [options] [command...]

-s, --socket <path>
    Specifies the Unix socket path for IPC communication. Overrides the default discovery mechanism.

-t, --type <type>
    Sets the message type for the request sent to Sway (e.g., command, get_workspaces, get_tree). The default type is command.

-m, --monitor
    Reads commands from standard input line by line, sending each as a separate IPC message. Useful for interactive scripting.

-p, --pretty
    Formats JSON responses with indentation and line breaks for improved human readability.

-h, --help
    Displays a help message with command usage and available options.

-v, --version
    Shows the swaymsg utility's version information.

swaymsg is the command-line utility used to interact with the running Sway Wayland compositor instance. It leverages Sway's Inter-Process Communication (IPC) interface, allowing users to send various commands to manipulate the desktop environment or to query its current state. This powerful tool is essential for scripting custom behaviors, dynamic configuration changes, and integrating Sway with other applications. Users can issue commands to manage windows, switch workspaces, control outputs, or retrieve detailed information about the compositor's internal tree structure, marks, and version. Designed as a direct equivalent to i3-msg for the i3 window manager, swaymsg maintains a similar syntax and functionality, making it familiar to i3 users transitioning to Wayland. It can execute single commands provided as arguments or continuously process commands from standard input, offering significant flexibility for advanced automation and customization of the Sway desktop. Its output, especially for queries, is typically in JSON format, facilitating parsing with tools like jq(1).

swaymsg requires a running Sway session to function, as it communicates directly with the compositor's IPC socket. Access to this socket is necessary, typically managed automatically when running within a Sway session, but it can be manually specified using the --socket option. Commands and queries sent to Sway are processed asynchronously, and their successful execution depends on the compositor's state and configuration. When providing complex commands or arguments, proper shell escaping is crucial to prevent misinterpretation. For querying system state, the output is often in JSON format, which necessitates external tools like jq(1) for effective parsing in scripts.

swaymsg supports various message types beyond just sending commands. Common types include command (to execute actions, e.g., 'workspace next'), get_workspaces (to list available workspaces), get_outputs (for monitor information), get_tree (a hierarchical view of windows and containers), get_marks (for named windows), and get_version (for software versions). These types allow for comprehensive control and monitoring of the Sway environment.

By default, swaymsg attempts to locate the Sway IPC socket via the SWAYSOCK environment variable. If SWAYSOCK is not set, it falls back to a standard path like /run/user/$(id -u)/sway-ipc.$(id -u).$(pidof sway).sock. This automatic discovery simplifies usage, but the --socket option provides explicit control for non-standard setups or debugging scenarios.

The ability of swaymsg to accept commands from standard input (via -m) and output structured JSON data (via -t get_...) makes it exceptionally powerful for scripting. It's often piped with tools like jq(1) to parse output, filter information, and automate complex tasks, such as creating dynamic workspace layouts, managing application launches based on system state, or displaying custom status bar information.

swaymsg was developed as an integral part of the Sway project, a re-implementation of the i3 window manager for the Wayland protocol. Its design closely mirrors i3-msg, providing a compatible command-line interface for interacting with the compositor. This lineage ensured that users familiar with i3 could easily transition to Sway, benefiting from a consistent control mechanism. Its development tracks that of Sway itself, evolving to support new features and IPC capabilities introduced in the compositor.

sway(1), sway(5), sway-ipc(7), i3-msg(1), jq(1)