The Spacetile field guide

Keyboard shortcuts and commands

Every action, its default keyboard shortcut and its text command, and how to run commands from Terminal or another app.

Last updated · Spacetile 1.2.1

Everything Spacetile does from the keyboard is a command: a short instruction such as focus west or place left. Each command can have a keyboard shortcut. You can also send the same commands from Terminal, scripts, Raycast or another hotkey app.

Most people only need the shortcuts. The tables below list every command with its default shortcut; “none” means it has no shortcut until you add one in Settings → Keys.

Default shortcuts

The default shortcuts are grouped by modifier keys, so each family is easy to remember:

Modifiers Family
⌥ (Option) Switch Spaces, focus windows and change the layout
⌥⇧ (Option-Shift) Move windows: swap, send to another Space, full screen
⌥⌃ (Option-Control) Place and size windows
⌥⇧⌃ (Option-Shift-Control) Preselect where the next window opens
⌃⇧ (Control-Shift) Join two windows into one tile

Directions use the H, J, K and L keys, as in Vim: H is left (west), J is down (south), K is up (north) and L is right (east).

Change a shortcut

  1. Open Settings → Keys. Every command is listed by family, with a search field.
  2. Click a shortcut and press the new keys. For a command with no shortcut, click Record shortcut.
  3. To move a whole family to different modifiers, click the family’s modifier keycaps, hold the new modifiers and release.

If the shortcut you press already belongs to another command, Spacetile moves it and says so, with Undo. Edit → Undo (⌘Z) takes back any change.

Spacetile won’t use these shortcuts, because macOS needs them: ⌃← and ⌃→ (switching Spaces, which Spacetile also uses itself when instant switching fails), ⌃↑ and ⌃↓ (Mission Control and App Exposé), ⌘Q, ⌘Tab and ⌘Space.

In config.json, shortcuts are written modifier-modifier-key, for example "alt-shift-h": "swap west". Modifiers are ctrl, alt (or opt), shift and cmd. Keys are letters, digits, punctuation as on a US keyboard, return, tab, space, delete, escape, left, right, up and down. See Configuration.

Spaces

Default key Command What it does
⌥1 … ⌥9, ⌥0 space 1 … space 10 Switch to that Space instantly, with no slide animation. Full-screen apps count, in their Mission Control place. Higher numbers work from the command line (space 12) if you have that many Spaces
⌥. / ⌥, space next / space prev Next or previous Desktop, wrapping round. From a full-screen app, the Desktop either side of it
⌥` space last The Space you were on before this one
⌥⇧1 … ⌥⇧0 send 1 … send 10 Send the focused window to that Space, and go with it if “Follow after sending” is on. A full-screen app’s Space can’t take it
⌥⇧. / ⌥⇧, send next / send prev Send the focused window to the next or previous Space
none display next / display prev Focus the display to the right or left. The pointer moves there, making it the active display
none send display next / send display prev Move the focused window to the Space showing on the display to the right or left

Focus

Default key Command What it does
⌥h / ⌥j / ⌥k / ⌥l focus west / south / north / east Focus the neighbouring tile. The pointer follows if “Mouse follows focus” is on
⌥n / ⌥p stack next / stack prev Cycle through the windows stacked in the focused tile, or the whole Space in Stack layout

Move

Default key Command What it does
⌥⇧h / j / k / l swap west … Swap the focused window with its neighbour
⌥⇧o pop out Swap the focused window with the window in the largest tile (the main tile under master and stack tiling). Between equal tiles, the topmost wins, then the leftmost. On the window you just popped out, it pops it back in
⌥⇧i pop in Swap the last popped-out pair back, from any window on the Space. Forgotten once either window closes, floats or leaves the Space
⌃⇧h / j / k / l join west … Put the focused window and its neighbour in that direction together in one tile, split the other way: side by side become one above the other, and stacked become side by side. Their order stays

Layout

Default key Command What it does
⌥z, ⌥m zoom Make the focused window fill the whole Space, or put it back. The other windows keep their arrangement underneath
⌥f float Take the focused window out of the tiling, or put it back
⌥e split Flip the focused window’s split between side by side and one above the other
⌥b, ⌥=, ⌥] balance Give every tile an equal share and remove empty tiles
⌥d layout bsp Tile this Space
⌥s layout stack Stack this Space: every window fills it; cycle with ⌥n / ⌥p
none layout float Leave this Space’s windows where you put them
⌥x mirror vertical Swap top and bottom across the Space
⌥y mirror horizontal Swap left and right across the Space
⌥r rotate 270 Rotate the layout anticlockwise. rotate 90 (clockwise) and rotate 180 also work
none retile Look at the Space’s windows again and re-apply its layout
none close Close the focused window, as its close button does

Place and size

These give the focused window a region of the Space. The other windows keep their own arrangement in what’s left. Where there aren’t enough windows to fill the shape, empty tiles called holes keep it (see Holes).

On a floating window, or any window on a Float-layout Space, place commands set the window’s size and position directly, as Rectangle does. On a Stack-layout Space they only work on floating windows. Grow, shrink and restore only work on tiled windows.

Default key Command What it does
⌥⌃h / j / k / l place left / bottom / top / right A full-height column or full-width row on that edge. Press again to cycle ½ → ⅔ → ⅓
none place left 3/4, place top 0.4, … A fixed share of that edge, as a fraction or a decimal between 0.05 and 0.95
⌥⌃y / u / b / n place top-left / top-right / bottom-left / bottom-right A quarter. The window shares its column with the neighbour below or above it, or with a hole
⌥⌃c place center The middle third; the other windows split either side
⌥⌃↑ place column Maximize height: a full-height column where the window already is, at its current width. At an edge the others keep their arrangement; in the middle they form a column either side. restore undoes it
none place top-left-sixth … place bottom-right-sixth One cell of a grid three columns wide and two rows high; other windows fill the rest in order
⌥⌃= / ⌥⌃- grow / shrink Move the window’s inner borders outwards or inwards by a tenth of the Space
⌥⌃r restore Undo the last run of place, grow and shrink on this Space
none border horizontal -100, border vertical 100, … Move the nearest border by that many points. Negative is left or up

Full screen

Full-screen apps get a Space of their own, which Spacetile counts among the Desktops but doesn’t tile (see Full-screen apps).

Default key Command What it does
⌥⇧f fullscreen Turn macOS full screen on or off for the focused window. A tiled window goes back to its tile afterwards
none fullscreen pair Put the focused window and its neighbour into Split View, each on the side it’s on now
none space fullscreen next / space fullscreen prev Go to the next or previous full-screen app on the active display, skipping Desktops

Preselect

Default key Command What it does
⌥⇧⌃h / j / k / l preselect west … The next new window opens on that side of the focused window. A teal hint shows where; the same key again cancels

Profiles

Default key Command What it does
none capture <name> Save every Space’s arrangement as a profile with that name. If the profile exists, its windows and layouts are replaced without asking; its icon, shortcut and other settings stay
none load <name> Apply a profile. Shortcuts you set in the profile designer are stored as these

See Profiles.

Spacetile

Default key Command What it does
none pause Pause or resume all tiling. While paused, Spacetile moves no windows, ignores window and Space commands and mouse gestures, and releases every shortcut except the ones for pause. Resuming lays out the current Space again. If you (or macOS Fill & Arrange) arranged its tiled windows neatly while paused, Spacetile keeps that arrangement; if windows overlap or leave a gap, the old tiling comes back
none toggle spacing Turn the padding and gaps off, so tiles meet edge to edge, or back on. Saved to config.json
none toggle border Turn the active window border on or off. Saved to config.json
none toggle dim Turn dimming the other windows on or off. Saved to config.json
none settings Open Settings. Opening Spacetile again from Finder, Spotlight or Raycast does the same, so Settings stays reachable when macOS hides the menu-bar item

settings and the toggle commands still work while tiling is paused.

Unbound by default

These commands have no shortcut until you add one in Settings → Keys or config.json:

  • display next|prev and send display next|prev
  • fullscreen pair and space fullscreen next|prev
  • layout float
  • rotate 90|180
  • retile and close
  • the fixed-fraction and sixth place commands
  • the border nudges
  • capture <name> and load <name>
  • pause, settings, toggle spacing, toggle border and toggle dim

Shortcuts from other tools

If you’re used to another window manager, Settings → Keys → Use Shortcuts From swaps in its default shortcuts, mapped onto Spacetile’s commands. You can also choose one in the Welcome guide when you first open Spacetile.

The preset is laid over Spacetile’s default shortcuts, so any shortcut you recorded yourself, including profile shortcuts, is replaced; Spacetile asks first. Spacetile’s defaults stay for everything the tool doesn’t bind. Where the tool uses a key Spacetile needs, Spacetile’s command moves to a new key in the tool’s style. Edit → Undo takes the whole change back. The maps are in KeyPresets.swift.

Tool What maps Not in Spacetile Spacetile commands moved to make room
Rectangle (its Recommended set; Raycast’s and Magnet’s sets match) Halves, quarters, thirds, two-thirds, maximize (zoom), maximize height, center, larger/smaller, restore, next/previous display Center two-thirds; Rectangle’s center keeps the window’s size, Spacetile’s takes the middle third place top, place bottom to ⌃⌥⌘↑ / ⌃⌥⌘↓
Spectacle (also Rectangle’s Spectacle set) Cycling halves, quarters, maximize, maximize height, center, larger/smaller, restore, displays Undo/redo; center keeping the window’s size none
AeroSpace Focus, move (swap), workspaces 1–9 (focus and send), back-and-forth, tiles and accordion (stack) layouts, resize Workspaces A–Z, moving a workspace to another monitor, toggling tile orientation with ⌥/ (⌥E splits the other way instead), service mode (join, float and flatten have direct shortcuts instead) space prev to ⌥[
Amethyst Fullscreen layout (stack), shrink/expand, focus and throw to the next screen, throw to Space 1–10 and left/right, float, pause, re-evaluate (retile), swap with main (pop out) Layout cycling; the tall, wide and column layouts (master and stack tiling is close to Tall: see Algorithms); main pane count; focus main; focus and swap round the layout; screens by number; show current layout; relaunch; focus-follows-mouse toggle swap west, swap east to ⌥⇧← / ⌥⇧→; preselect west, preselect east to ⌃⌥⇧, / ⌃⌥⇧.
BetterStage (Standard) Stages 1–9 (focus and send), next/previous, retile, focus IJKL, halves, quarters, thirds, two-thirds, maximize, center Stages Bar, new and close stage, window mode cycling, center two-thirds place top, place bottom to ⌃⌥⌘↑ / ⌃⌥⌘↓; place column to ⌃⌥⇧↑
ShiftPlus Previous workspace, cycle workspaces Capturing a workspace by shortcut (use Save Current Layout… in the menu-bar panel) none

There’s no preset for:

  • Raycast, Moom and yabai, which ship no default shortcuts. Raycast’s own presets copy Rectangle, Magnet and Spectacle, so choose Rectangle or Spectacle.
  • macOS’s built-in tiling, which uses fn⌃ shortcuts that other apps can’t register. They work alongside Spacetile anyway: see macOS tiling.

None of these tools’ defaults cover preselect, stack cycling, mirror, rotate, balance, the split toggle, join (except through AeroSpace’s service mode) or applying profiles. Those keep Spacetile’s shortcuts.

Installed app

Install the spacetile command to run commands from Terminal or scripts.

  1. Make sure Spacetile is in your Applications folder (/Applications or ~/Applications), and open it.
  2. Open Settings → General → Command line and click Install Command…. Enter your administrator password if macOS asks.
  3. Wait for the button to show Installed.
  4. In Terminal, run a command:
spacetile focus east

The window to the right of the focused one takes focus. Other examples:

# Apply a profile you saved as Writing
spacetile load Writing
# Put the focused window in the left two-thirds
spacetile place left 2/3

The installer creates /usr/local/bin/spacetile, a link to the app’s own program (/Applications/Spacetile.app/Contents/MacOS/Spacetile for the usual location). You don’t need to change your shell configuration.

The command sends its instruction to the Spacetile that’s already running and returns straight away. It doesn’t start Spacetile, and it doesn’t report whether the layout changed. Turn on Open at login in Settings → General so Spacetile is always running.

Check the command

command -v spacetile

This prints:

/usr/local/bin/spacetile

If it prints nothing:

  1. Open a new Terminal window, then try again.
  2. Make sure /usr/local/bin is on your PATH, or call /usr/local/bin/spacetile directly.
  3. Remove any older shell alias or function called spacetile from your shell configuration; it takes precedence over the command.

If something is already at /usr/local/bin/spacetile

If a file, folder or another link already uses that path, the installer leaves it untouched and Settings explains the conflict. Look at what’s there (ls -l /usr/local/bin/spacetile), move or remove it if you don’t need it, then click Install Command… again.

Move or remove the command

Updates keep the link working. If you move Spacetile to a different folder, remove the old link (sudo rm /usr/local/bin/spacetile) and install the command again from Settings. Removing the link doesn’t remove the app or its settings, and Restore Defaults in Settings doesn’t remove the link.

You can also run the app’s program directly without installing anything:

/Applications/Spacetile.app/Contents/MacOS/Spacetile place left

From a source checkout

If you’ve cloned Spacetile’s source, app/scripts/spacetile-ctl sends commands to the running app the same way:

app/scripts/spacetile-ctl place left

Other key binders

Raycast, skhd and Karabiner-Elements can run Spacetile’s commands instead of Spacetile’s own shortcuts. To use only theirs, turn off Use Spacetile’s shortcuts at the top of Settings → Keys. Spacetile then registers no shortcuts, and keeps yours for when you turn it back on.

Install the command first, and use its full path, /usr/local/bin/spacetile, so the binding works whatever the tool’s PATH is.

Raycast

The Spacetile extension has a Raycast command for every action in Settings → Keys, each of which you can give a Raycast alias and hotkey. Run Command sends any other command, such as load Work.

skhd

Add lines like these to ~/.skhdrc:

alt - h : /usr/local/bin/spacetile focus west
alt - 1 : /usr/local/bin/spacetile space 1
alt + shift - 1 : /usr/local/bin/spacetile send 1
alt + ctrl - h : /usr/local/bin/spacetile place left

Karabiner-Elements

Add a rule under Complex Modifications. Karabiner runs commands without your shell’s PATH, so use the full path:

{
  "description": "Spacetile: ⌥H focuses the window on the left",
  "manipulators": [
    {
      "type": "basic",
      "from": { "key_code": "h", "modifiers": { "mandatory": ["option"] } },
      "to": [{ "shell_command": "/usr/local/bin/spacetile focus west" }]
    }
  ]
}

See also