spatial(1)

📦
version 7 · 2 versions
, in nixos 26.05

💖 spatial(1) — the vibe check 💖

okay so real talk, this is the spatial page from the General Commands Manual, section 1, and it's genuinely one of my faves. sit down, grab a strawberry 🍓, let's go.

✨ NAME ✨

spatial — bestie, it implements a spatial model inspired by Material Shell and Paper WM, for sway. no cap.

🌸 SYNOPSIS 🌸

spatial

that's it. that's the whole synopsis. iconic minimalism 💅

🦋 DESCRIPTION 🦋

Spatial Shell is a daemon implementing a spatial model inspired by Material Shell, for i3 and sway. More precisely — and this is the part that's giving main character energy — it organizes your windows within a grid whose rows are the workspaces of your favorite WM. the way that works?? obsessed. 🔥

In a nutshell, Spatial Shell allows you to:

  • Move the focus within the grid: on the left or on the right within the current workspace, or on the focused window of the upper or lower workspace. In the former case, the current workspace does not change, while in the latter it does. yes, that distinction matters, write it down 📝
  • Move the focused window within the grid: to the left or to the right within the current workspace, or to the upper or lower workspace. In the former case, the focused window is swapped with its neighbor, while in the former it is inserted at the right of the previously focused window within this row. (and yes, that sentence says "former" twice — I'm just the messenger, don't come for me 😭)
  • Configure how many windows are displayed at most within a given workspace (for when the workspace uses the column layout). lowkey so useful.
  • Toggle between the Column and maximize layout for the current workspace (see the LAYOUTS section down below 👇)

Spatial Shell consists in a daemon (spatial) and a client (spatialmsg(1)) communicating with a IPC protocol (spatial-ipc(7)). The most straightforward way to run the Spatial Shell daemon is via your favorite WM configuration file. fr fr, just drop it in there:

# Assuming `spatial` is available from $PATH
exec spatial

Once spatial is running, you can assign bindings to interact with it using spatialmsg(1) as part of the configuration of your favorite WM 🎀:

# Assuming `spatialmsg` is available from $PATH
bindsym $mod+h exec $spatialmsg "focus left"
bindsym $mod+l exec $spatialmsg "focus right"
bindsym $mod+k exec $spatialmsg "focus up"
bindsym $mod+j exec $spatialmsg "focus down"

For more information about the commands (including the exact syntax 👀) which can be sent to spatial via spatialmsg(1), see spatial(5). iykyk.

🎀 LAYOUTS 🎀

In Spatial Shell, workspaces can use one of two modes: maximize and column. Each layout determines the strategy to display and organize the windows of the workspace. two modes, both slay:

  • Maximize: The focused window takes up the whole workspace. one window, whole screen, main character energy 👑
  • Column: Up to a fixed number of windows are displayed on the workspace, the rest is hidden. the extras are just backstage, waiting their turn 🧚

💜 CONFIGURATION 💜

spatial(5) searches for a config file in $XDG_CONFIG_HOME/spatial/config. If $XDG_CONFIG_HOME is unset, it defaults to $HOME/.config. found her ✨

The config file of Spatial Shell is a list of commands (one per line). Additionally, a line starting with a # is ignored — but inline comments are not supported, that is, it is not possible to add a comment at the end of a valid command. so sad but so true 🫶. See spatial(5) for information about supported commands.

Spatial Shell is a lot more enjoyable to use with some visual aids to help you visualize the state of the grid. To that end, spatial can be configured to send a signal (SIGMIN+8) to a status bar everytime the configuration of the grid changes (that is when the focus or the order of the windows changes). visual feedback?? we love to see it 💖

spatial uses pkill(1) to send the signal, and does so only when it has been provided the name of the status bar program with the status_bar_name command. For instance, assuming you are using waybar(5), add this line to your Spatial Shell config file:

status_bar_name "waybar"

and boom, status bar goes brrr 🌈

⭐ IPC COMMANDS ⭐

Though spatialmsg(1) is generally preferred, you may interact with Spatial Shell directly via IPC, see spatial-ipc(7). This is typically what spatialblock(1) does to reduce latency as much as possible. speed demon behaviour, honestly 💀

The socket created by Spatial Shell is $XDG_RUNTIME_DIR/spatial.sock. If $XDG_RUNTIME_DIR defaults to /tmp, that is the socket is /tmp/spatial.sock. keep that path in your notes bestie 🗒️

🧚 ENVIRONMENT 🧚

The following environment variables have an effect on Spatial Shell. yes, all four, no skipping 🙈

  • SWAYSOCK — Specifies the path to the socket spatial will connect to in order to interact with sway. If unset, defaults to I3SOCK.
  • I3SOCK — Specifies the path to the socket spatial will connect to in order to interact with i3, when SWAYLOCK is unset. If required but unset, spatial will exit with an error. (heads up: that's SWAYLOCK exactly as written — copy it character for character, don't be clever 💅)
  • XDG_CONFIG_HOME — If set, tells Spatial Shell where to find its config file. If unset, its value is defaulted to $HOME/.config.
  • XDG_RUNTIME_DIR — If set, tells Spatial Shell where to create the socket other tools can use to control it. If unset, defaults to /tmp. For more information, see section IPC COMMANDS.

👑 AUTHOR 👑

Developed by Thomas Letan <lthms@soap.coffee>. Fore more information about Spatial Shell development, see <https://github.com/lthms/spatial-shell>. (typo "Fore" is theirs, keeping it, we respect the source 🙏) give the dev some love, they ate 🔥

🌈 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. shoutout sway, the blueprint, the blueprint fr 🫶🌸

and that's the whole page bestie!! 💜 this was spatial(1) from the General Commands Manual — dated 1980-01-01, and the page signs off as spatial(1) one last time. go forth, arrange your windows in a grid, and live your spatial fantasy ✨🎀🦋

📦 where this page comes from