spatial-ipc(7)

📦
version 7 · 2 versions
, in nixos 26.05

💅 spatial-ipc(7)

okay so first things first, the vibe: this is a page from the Miscellaneous Information Manual, and its whole name is spatial-ipc(7). say it with me now — spatial-ipc is the IPC protocol for Spatial Shell ✨

🎀 NAME

spatial-ipc — the IPC protocol for Spatial Shell, bestie 💖

🌸 DESCRIPTION

This man page is literally the blueprint for the IPC protocol that third-party tools can use to control a Spatial Shell instance, or to get info out of one. you're not just reading docs, you're getting the keys to the kingdom 👑

So, similarly to sway(1), the IPC protocol uses a UNIX socket as the method of communication. The path to the socket is $XDG_RUNTIME_DIR/spatial.sock, and if $XDG_RUNTIME_DIR is unset, it defaults to $HOME/.config.

Write that down. Actually no — I wrote it down for you. slay 🫶

🦋 MESSAGE AND REPLY FORMAT

The format for messages and replies is exactly the same as sway. See sway-ipc(7). not "similar to", not "inspired by" — exactly the same. no cap 💀

🌈 MESSAGES AND REPLIES

The following message types and their respective reply are currently supported. here's the whole menu 🍓

  • 0 — RUN_COMMAND — Runs the payload as a Spatial Shell command
  • 1 — GET_WINDOWS — Get the list of windows of the current workspace
  • 2 — GET_WORKSPACES — Get the list of workspaces with at least one window.
  • 3 — GET_WORKSPACE_CONFIG — Get the configuration of the current workspace.

0. RUN_COMMAND 👑

MESSAGE

Runs the payload as a Spatial Shell command. See spatial(5) for a list of the commands supported by Spatial Shell. it's giving "just tell me what to do and I'll do it" energy 💅

REPLY

A JSON object with a success boolean property, and its whole job is to witness whether the command has been successfully parsed and interpreted by the Spatial Shell instance, or whether something went wrong 😭

Examples of reply:

{ "success": true }
{ "success": false }

1. GET_WINDOWS 🪟

MESSAGE

Get the list of windows of the current workspace. No payload expected — don't send one, it's not that kind of party 🙈

REPLY

The reply of the GET_WINDOWS message is a JSON object with the following properties.

  • focus — integer — The index of the window currently holding sway's focus.
  • windows — list — The list of windows managed by the current workspace.

A window is encoded as an object with the following properties.

  • app_id — string — The app_id of the window, as reported by sway.
  • name — string — The name of the window, as maintained and reported by sway.

Example of reply:

{ "focus": 0,
  "windows":
    [ { "app_id": "kitty", "name": "zsh" },
      { "app_id": "firefox",
        "name":
          "Ubuntu Manpage: scdoc - document format for writing manual pages — Mozilla Firefox" } ] }

2. GET_WORKSPACES 🌸

MESSAGE

Get the list of workspaces with at least one window. No payload expected — again, zero payload, we're keeping it clean ✨

REPLY

The reply of the GET_WORKSPACES message is a JSON object with the following properties.

  • focus — integer — The index of the workspace currently focused by sway.
  • workspaces — list — The list of workspaces containing at least one window.

A workspace is encoded as an object with the following properties.

  • index — int — The position of the workspace in Spatial Shell's gride.
  • focused_windows — window — The description of the window currently holding the focus.
🫶 bestie heads up: yes, this table says focused_windows (plural) while the example down below writes focused_window (singular). that's literally what the page says, so I'm not gonna "fix" it and gaslight you. iykyk — copy the example if you want the exact spelling 👀

Example of reply:

{ "focus": 1,
  "workspaces":
    [ { "index": 1, "focused_window": { "app_id": "kitty", "name": "zsh" } },
      { "index": 3,
        "focused_window":
          { "app_id": "firefox",
            "name":
              "spatial-shell/README.md at main · lthms/spatial-shell · GitHub — Mozilla Firefox" } } ] }

3. GET_WORKSPACE_CONFIG 🎀

MESSAGE

Get the configuration of the current workspace. No payload required. main character message: asks for nothing, gets everything 💜

REPLY

  • layout — string — Either column or maximize.
  • column_count — int — The maximum number of windows displayed by Spatial Shell when the layout is column.

Example of reply:

{ "layout": "column", "column_count": 2 }

⭐ AUTHOR

Developed by Thomas Letan <lthms@soap.coffee>. For more information about Spatial Shell development, see <https://github.com/lthms/spatial-shell>.

🧚 ACKNOWLEDGMENT

Spatial Shell could not have been possible without sway, which remains a reference and a significant source of inspiration for the software architecture of this project, including for the wording of several man pages. real ones know 🌈 like, sway ate and left no crumbs, and we're forever grateful 🫶

💫 and that's the whole page, bestie! this little number is spatial-ipc(7) from the Miscellaneous Information Manual, dated 1980-01-01 — yes, that date, iconic, no notes 💀✨ go forth and talk to your socket 💅💖
📦 where this page comes from