swaymsg(1)

📦
version 1.12_rc3 · 12 versions
, in alpine 3.24

💅 swaymsg(1) — the group-chat guide

okay so bestie, picture this: it's a manual page, it's from the General Commands Manual, and its whole personality is swaymsg. Say it with me — swaymsg. That's the vibe. It's the little bestie that talks to a running instance of sway over the IPC socket. That's it. That's the whole job. 🎀

✨ NAME ✨

swaymsg — send messages to a running instance of sway over the IPC socket. Like sliding into sway's DMs, but with JSON. 🦋

🌸 SYNOPSIS 🌸

swaymsg [options...] [message]

💖 OPTIONS 💖

  • -h, --help — shows the help message and dips. icon 🫶
  • -m, --monitor — keeps watching for responses until it gets killed, instead of exiting after the first response. Lowkey important: this one can only be used with the IPC message type subscribe. And if there's a malformed response, or someone requested an invalid event type, swaymsg will stop monitoring and exit. no cap.
  • -p, --pretty — gives you pretty output even when you're not on a tty. Ngl it's not available for all message types, so don't come for me if it ghosts you.
  • -q, --quiet — sends the IPC message but does not print the response from sway. silent treatment, but make it productive 💀
  • -r, --raw — uses raw JSON output even if you are on a tty. crunchy and unfiltered, we love her.
  • -s, --socket <path> — use the socket path you specify. Otherwise swaymsg will ask sway where the socket is — which is the value of $SWAYSOCK, then of $I3SOCK.
  • -t, --type <type> — specifies the type of IPC message. details below, keep scrolling bestie ⬇️
  • -v, --version — prints the version (of swaymsg) and quits. flex and leave. ✨

👑 IPC MESSAGE TYPES 👑

<command>

The message is a sway command — literally the same commands you can bind to keybindings in your sway config file. It gets executed immediately. main character energy fr fr.

See sway(5) for a list of commands.

swaymsg can return pretty printed (standalone-default) or JSON-formatted (--raw) output. For detailed documentation on the returned JSON-data of each message type listed below, refer to sway-ipc(7). And heads up: the JSON-format can contain more information than the pretty print. she's not withholding, she's just thorough 💅

Tips:

  • Command expansion is performed twice: once by swaymsg, and again by sway. So if you have quoted multi-word strings in your command, enclose the entire command in single-quotes. For example, use swaymsg 'output "Foobar Display" enable' instead of swaymsg output "Foobar Display" enable. Also note that comma separated options also count as multi-word strings, because commas can be used to execute commands on the same line. 😭 yes really.
  • If you're providing a command that contains a leading hyphen (-), insert two hyphens (--) before the command to signal to swaymsg not to parse anything beyond that point as an option. For example, use swaymsg -- mark --add test instead of swaymsg mark --add test. protect her from misreading the vibe check 🫶

get_workspaces

Gets a list of workspaces and their status. the roster.

get_inputs

Gets a list of current inputs.

get_outputs

Gets a list of current outputs.

get_tree

Gets a JSON-encoded layout tree of all open windows, containers, outputs, workspaces, and so on. the whole family tree, gorgeous 🌈

get_seats

Gets a list of all seats, its properties and all assigned devices.

get_marks

Get a JSON-encoded list of marks.

get_bar_config

Get a JSON-encoded configuration for swaybar.

get_version

Get version information for the running instance of sway.

get_binding_modes

Gets a JSON-encoded list of currently configured binding modes.

get_binding_state

Gets JSON-encoded info about the current binding state.

get_config

Gets a copy of the current configuration. Doesn't expand includes. take her as she is 💜

send_tick

Sends a tick event to all subscribed clients. tiny notification, big impact ⭐

subscribe

Subscribe to a list of event types. The argument for this type should be provided in the form of a valid JSON array. If any of the types are invalid, or if a valid JSON array is not provided, this will result in a failure. For a list of valid event types and the data returned with them, refer to sway-ipc(7). read the docs bestie, i'm begging 🙈

🔥 RETURN CODES 🔥

  • 0 — Success. slay. ✅
  • 1 — swaymsg errors such as invalid syntax, unable to connect to the ipc socket, or unable to parse sway's reply. 😭
  • 2 — Sway returned an error when processing the command (ex. invalid command, command failed, and invalid subscription request). 💀

🌟 SEE ALSO 🌟

sway(5) sway-bar(5) sway-input(5) sway-output(5) sway-ipc(7)

okay that's the whole page bestie, you ate that 🫶 this was the General Commands Manual edition, dated 2026-04-26 — yes, that's the date, and the version/source lives right there in this sign-off, so i didn't lose it, i just made it cute. it's the swaymsg(1) eraaaaa 🎀✨💖

📦 where this page comes from