Skip to content
EN
Download

Command line

TilingBud is controlled from scripts and tools such as skhd, Hammerspoon or Raycast with the tilingbud tool. The tool sends its arguments to the running app and prints the reply; the app parses and runs the command. The same commands are the values of [shortcuts] in the configuration file, so a command means the same everywhere.

The tool is inside the app: TilingBud.app/Contents/Helpers/tilingbud. To have tilingbud in the terminal, choose Install Command Line Tool… in TilingBud’s menu (or Settings > Command Line), as with VS Code’s “Install ‘code’ command in PATH”:

  • TilingBud links tilingbud into /usr/local/bin when it can write there, else into ~/.local/bin or ~/bin if that folder is on your shell’s PATH.

  • Otherwise (on Apple silicon /usr/local/bin belongs to root) macOS asks for your password in its own dialog and TilingBud puts the link into /usr/local/bin. By hand, the same is:

    Terminal window
    sudo mkdir -p /usr/local/bin && sudo ln -sf /Applications/TilingBud.app/Contents/Helpers/tilingbud /usr/local/bin/tilingbud
  • A tilingbud that is already on the PATH, for example from Homebrew, is used as it is. Settings shows where the command is, repairs a link after the app was moved and removes the link again (Uninstall).

The tool works from wherever the app is, because it talks to the running app through its socket; a Homebrew cask or a package installer only has to link it.

A space target is a space number, a space name, next or prev:

  • A name (space --focus Finance, quoted when it has blanks: window --space "Finance and Taxes") is the name of a [[space]] entry, found by the space’s identifier wherever the space is now, so it keeps naming the same space when the numbers shift (after a restart or when a display is plugged in or out).
  • A number without --display counts over all displays in Mission Control’s order (index in query --spaces): with ten spaces on the main display, space --focus 11 is the first space of the second display, from whichever display. With --display <n|next|prev> (numbered as query --spaces lists them in display) it counts on that display as Mission Control does, from 1 (position).
  • next and prev go over the spaces of the active display (space --focus) or the window’s display (window --space), or of the display --display names; they skip full-screen spaces and do nothing at either end.

A space that is already shown on another display gets the focus there.

Terminal window
tilingbud space --focus 3 # show space 3
tilingbud space --focus next # the space to the right; also prev
tilingbud space --focus 1 --display 2 # the first space of the second display
tilingbud space --focus recent # back to the space shown before; again to return
tilingbud space --focus Finance # the space named Finance, on whichever display it is
tilingbud space --label Finance # name the shown space (its [[space]] name); space --label alone removes the name
tilingbud space --create # add a space (Mission Control through Accessibility)
tilingbud space --destroy 4 # remove space 4; without a number the shown space
tilingbud space --swap 5 # exchange the windows, name and layout of the shown space and space 5 (same display)
tilingbud space --move 1 # bring the shown space to place 1; the spaces in between move one place over
tilingbud space --tile # arrange the shown space anew: side by side, equal shares; also --tile 2
# (a space whose layout is off becomes bsp, as with --layout bsp)
tilingbud space --balance # every window of the shown bsp space gets an equal area
tilingbud space --raise-floating # bring the floating windows of the shown space to the front, in their order;
# the one focused last gets the focus (once: the next click on a tiled window covers them again)
tilingbud space --layout main # arrange the shown space as main (off, bsp, main, stacked, scroll); kept after a restart,
# the configuration is not changed (--layout reset: back to it)
tilingbud space --layout off 4 # leave the windows of space 4 alone
tilingbud space --layout next # the next mode of [tiling] layout_cycle; also prev
tilingbud space --layout recent # back to the mode the space had before
tilingbud space --layout reset # back to the layout saved for the space (Settings, [[space]] layout)
tilingbud space --layout save # save the shown space's current mode as its [[space]] layout
tilingbud space --layout-save mail # save the shown space's arrangement as layouts/mail.json, as the variant
# for its display, with the document or link of each window; applying it
# opens what is missing; --replace saves over an existing layout; the
# space keeps it from then on (layout_preset)
tilingbud space --layout-save tb --no-details --no-open --float-others --no-keep 3 # space 3: only the apps,
# nothing opened, windows that take no place float while the layout arranges
# the space, and space 3 does not keep it; --open-at-launch opens what
# its places miss when TilingBud starts, on every space that keeps it
tilingbud space --layout-apply mail # arrange the shown space by the saved layout mail; a place whose window is
# missing takes no area; its window goes there when it opens (or is opened)
tilingbud space --layout-apply tb 3 # the same for space 3; it is shown first when something is opened
# applying writes layout_preset of the space: it stays until --layout-clear
tilingbud space --layout-save # without a name: a window asks for the name and the choices
tilingbud space --layout-choose # a window shows the saved layouts with their sketches; Return arranges
# the shown space by the selected one
tilingbud space --layout-clear # stop using the applied layout (also of space <index>): no waiting places, no floating others, no parking
tilingbud space --overview # every window of the space (or of space <index>) to scale, a scroll row at full length; click or Return goes to one
tilingbud space --rotate 90 # turn the arrangement of the shown bsp space clockwise; also 180, 270
tilingbud space --mirror y # swap left and right (x: top and bottom)
tilingbud space --main-count +1 # one more window in the main area of the shown main space; also -1
tilingbud space --main-ratio +0.05 # a larger main area (0.1 to 0.9); also -0.05
tilingbud space --toggle auto-balance # turn [tiling] auto_balance on or off (written to the file)
tilingbud space --toggle gaps # no gaps on the shown space for now; again for the configured gaps
tilingbud space --toggle control-bar # show the shown space's control bar, or hide it, until [control_bar] show changes
tilingbud space --toggle show-desktop # move the windows aside to show the desktop, or bring them back
tilingbud space --toggle mission-control # open Mission Control, or close it
tilingbud space --inner-gap 7 --outer-gap 5 # points between the windows and at the edges of the shown space
tilingbud space --outer-gap +2 # 2 points more on every edge (-2: fewer); reset: the configured value again
Terminal window
tilingbud window --space 3 # move the focused window to space 3
tilingbud window --space 3 --follow # ... and show space 3 with the window focused
tilingbud window --space next --no-follow # ... and stay, whatever the configured default says
tilingbud window --space 2 --app # move all windows of the focused window's app
tilingbud window --space 2 --id 4711 # move window 4711 (ids from query --windows)
tilingbud window --space 1 --display next # to the first space of the next display
tilingbud window --display next # to the space shown on the next display; also prev, recent or a number
tilingbud window --toggle float # leave the focused window out of the layout, or arrange it again (until it closes)
tilingbud window --toggle float --app # the same for its app: its rule gets or loses float = true
tilingbud window --toggle float --id 4711 # the same for window 4711
tilingbud window --toggle all-spaces # the focused window's app on every space, or back on the shown space only; a window on all spaces floats
tilingbud window --toggle all-spaces --id 4711 # the same for the app of window 4711
tilingbud window --toggle float --grid 29:4:1:1:2:27 # and put it in the middle half when it floats now
tilingbud window --menu # the window menu at the focused window: spaces, float, layout, rule
tilingbud window --focus 4711 # focus window 4711, showing its space
tilingbud window --focus west # focus the nearest window to the west; also east, north, south
tilingbud window --swap east # exchange places with the arranged window to the east
tilingbud window --warp east # move into the area of the arranged window to the east (bsp)
tilingbud window --resize east 50 # move the window's east edge 50 points outwards; -50 moves it inwards
tilingbud window --ratio 0.6 # the window takes 60 % of the area it shares with its neighbor (bsp), or the main area (main); also +0.05, -0.05
tilingbud window --ratio next # the next share of [tiling] ratio_steps (½, ⅔, ⅓), from the step nearest to the share now; prev goes back
tilingbud window --insert south # the next new window goes below this one (bsp); the same again clears it
tilingbud window --swap main # exchange places with the first main window (main)
tilingbud window --promote # the main window in main, first in stacked, the first half in bsp
tilingbud window --focus stack.next # the next window of a stacked space or of the window's stack (bsp), wrapping around; also stack.prev
tilingbud window --stack west # put the window into the cell of the window to the west, first in its stack (bsp); also a window id
tilingbud window --unstack # take the window out of its stack into a cell of its own beside it
tilingbud window --focus east # scroll: the window of the next column, scrolled into view; north, south within the column
tilingbud window --swap west # scroll: exchange the focused column with the one to the west
tilingbud window --warp west # scroll: put the window at the bottom of the column to the west
tilingbud window --unstack # scroll: take the window out of its column into a column of its own right of it
tilingbud window --stack west # scroll: put the window into the column to the west as a tab; stack.next and stack.prev go through the tabs
tilingbud window --ratio 1 # scroll: the focused column as wide as the screen (0.1 to 1); also +0.1, -0.1
tilingbud window --ratio next # scroll: the next width of [tiling] scroll_widths (½, ⅔, full); prev goes back
tilingbud window --center # scroll: put the focused column in the middle of the screen once
tilingbud window --resize south 100 # scroll: 100 points more height for the window, from the one below it; east, west: the column's width
tilingbud window --height next # scroll: the next share of [tiling] scroll_heights for a window sharing its column; also 0.6, +0.1, prev
tilingbud space --balance # scroll: every column as wide as the focused one, equal heights in each column
tilingbud window --focus floating.next # the next floating window of the space in focus order, brought forward; also floating.prev
tilingbud window --focus recent # the window that had the focus before this one on its space
tilingbud window --focus next # the next arranged window in reading order, wrapping; also prev, first, last
tilingbud window --focus index:3 # the third window of the space as the control bar lists it; in scroll the third column
tilingbud window --focus mouse # the window under the pointer
tilingbud window --label term # name the focused window for this session; --focus, --swap and --warp take the name
tilingbud window --focus term # focus the window labeled term, showing its space; window --label alone removes the label
tilingbud window --swap recent # swap and warp take the same window choices as --focus
tilingbud window --toggle zoom-fullscreen # cover the whole space, the layout stays behind; again to go back
tilingbud window --toggle zoom-parent # cover the area the window shares with its neighbor in the layout
tilingbud window --toggle split # turn the split around the window: side by side or on top (bsp)
tilingbud window --toggle native-fullscreen # macOS full screen on a space of its own, or back; also --id 4711
tilingbud window --toggle expose # App Exposé of the app in front, or close it
tilingbud window --grid 1:2:0:0:1:1 # a floating window on the left half (rows:cols:x:y:w:h, cells from 0)
tilingbud window --center # a floating window in the middle of its space
tilingbud window --move 40 -20 # a floating window 40 points right and 20 up
tilingbud window --close # close the focused window as its close button does; also --id 4711
tilingbud window --minimize # into the Dock; also --id 4711
tilingbud window --deminimize --id 4711 # back from the Dock (a minimized window never has focus, so it is named)

Without --follow the window moves alone (--no-follow says so explicitly). With follow, the window is moved, its space shown and the window focused; when a step fails the message names it, and the steps before it are not undone (a window that moved stays moved). Without follow the focus stays on the space the window left, on its most recently focused other window (macOS would keep the moved window focused on its new display, and the pointer would follow it). next/prev of window --space are relative to the window’s own space.

  • --focus by direction looks at every window of the shown space, arranged or not, and does nothing when no window lies in that direction.
  • In scroll, a direction goes along the row by its columns, also to a column out of view, which is then scrolled into view.
  • In stacked, east and south focus the next window of the stack, west and north the one before, the space’s floating windows come after the stack, and nothing happens past either end.
  • --insert marks the side on the window’s border until the next window arrives; a zoomed window has a border twice as wide and ends its zoom when it closes, floats or moves to another space.
  • space --main-count and --main-ratio hold for that space until TilingBud restarts, like a divider dragged with the mouse; the defaults are [tiling] main_count and main_ratio.
  • --grid, --center, --move and --resize place windows the layout does not arrange (floating windows, windows on off spaces) inside the usable area of their space; --grid, --center and --move refuse an arranged window, and --resize moves its edge in the layout instead.
Terminal window
tilingbud display --focus next # the last active window of the next display, or its shown space
tilingbud display --focus recent # back to the display that had the focus before
tilingbud display --focus 2 # display 2, numbered as query --spaces lists them in display

With one display, display --focus and window --display do nothing and succeed. space --inner-gap and --outer-gap take values within 0 to 200 points (outer gaps 0 to 1000), and setting one turns the gaps on again.

These commands are mostly what a shortcut in [shortcuts] runs: one key that brings an app to the front on its space, or starts it ("rctrl+t" = "app --open iTerm"); one key that presses another key or types a text in the app in front; and modes, a second set of shortcuts that a key turns on and off. Unlike macOS’s open -a, app --open shows the app’s space and focuses the window it had last. From the command line they do the same, for scripts.

Terminal window
tilingbud app --open iTerm # start iTerm, or bring it to the front with its space
tilingbud app --open com.apple.Safari --url https://example.com # a bundle identifier; open the link in it
tilingbud app --open com.microsoft.VSCode --file ~/notes.md # open the file in the app
tilingbud app --open Terminal --new --args -v # another instance, started with these arguments
tilingbud key --send cmd+t # a key press to the app in front, keys as in [shortcuts]
tilingbud key --type Kind regards # type the text in the app in front (the words after --type)
tilingbud shortcuts --mode resize # turn on the mode [shortcuts.mode.resize]
tilingbud shortcuts --mode default # back to the shortcuts of [shortcuts]

app --open takes an app’s bundle identifier or its name (case does not matter, .app may be left out): a name is looked up among the running apps first, then in /Applications, /Applications/Utilities, /System/Applications, /System/Applications/Utilities and ~/Applications. A running app comes to the front with the window that had the focus last, and its space is shown as for window --focus; --new starts another instance instead. --file and --url open a document or link in the app (one of them); --args passes everything after it to the app when it starts. An app that is not found is an error.

A key press sent with key --send never runs one of TilingBud’s own shortcuts. shortcuts --mode with a name no mode has is an error that lists the modes.

Terminal window
tilingbud query --spaces # all spaces as JSON
tilingbud query --spaces index,label # only these fields of each space
tilingbud query --displays # the displays with their spaces as JSON
tilingbud query --windows # all windows as JSON
tilingbud query --windows id,app,floating # only these fields of each window
tilingbud query --windows --space 2 # windows of space 2 and the windows shown on every space
tilingbud query --windows --all # also app windows on another level, which TilingBud leaves alone (with "level")
tilingbud query --capabilities # which features work on this Mac
tilingbud query --shortcuts # the shortcuts of [shortcuts] and of every mode, and the mode that is on
tilingbud query --rules # the window rules with their index, line and keys
tilingbud query --signals # the signals of the configuration (the command line cannot add or run them)
tilingbud subscribe space_changed window_focused # one JSON line per event as it happens, until stopped; without names every event
tilingbud query --window # what TilingBud sees of the focused window, and why it is tiled or not
tilingbud query --window 4711 # the same for window 4711
tilingbud help # every command with its flags; the same without arguments
tilingbud window --help # the flags of one domain
tilingbud doctor # a report to attach to a support ticket
tilingbud update --check # looks for a new version: "1.4.0 available (installed 1.3.2)" or "TilingBud 1.3.2 is current"
tilingbud update # opens the update window with Install and Relaunch

Fields of query --spaces: display focused id index label position type visible windows (position is the number on its display, index the place over all displays); of query --windows: app floating focused frame id level pid space state sticky title; of query --displays: focused frame id index name spaces uuid. An unknown field is a usage error.

--all adds the windows of apps that are not on the level of normal windows (level 0): an app can put its window below the others (level -1) or above them for a while. TilingBud does not list, show or arrange them; they come last and carry their level, the other windows have no level.

query --window shows the window’s Accessibility role and subrole (only AXWindow/AXStandardWindow windows are tiled; dialogs, sheets and panels float), what the window server says about it (a document window, its corner radius), the rules that match it (by line) and the layout’s decision with its reason, for example floats: a window rule says float = true or the layout of space 3 is off: TilingBud leaves its windows alone.

Terminal window
tilingbud config --reload # read the configuration file now
tilingbud rules --apply # apply the window rules to every open window
tilingbud rules --add app=Calculator float=true # write a [[rule]] with these keys and apply the rules
tilingbud rules --add --one-shot app=Finder space=2 # apply once to the open windows, write nothing (space, float, all_spaces)
tilingbud rules --remove 3 # remove rule 3 (index from query --rules); a name removes every rule of that app
tilingbud refresh # read spaces and windows again
tilingbud settings # open the Settings window (also while the menu bar item is hidden)

A query prints its JSON document to standard output. Messages (configuration applied) and errors go to standard error.

Status Meaning
0 done
1 the command ran and failed (space 12 does not exist (spaces: 9))
2 the command was not understood; the message names the problem and the valid flags
3 TilingBud was not reached (not running, or the socket belongs to someone else), or the tool and the app do not fit (see below)

The tool is a thin wrapper: it understands no command and sends its arguments as they are, so a tool keeps working with newer TilingBud versions and new commands need no new tool. Only a change of the wire format between tool and app raises its protocol number (tilingbud --protocol prints the tool’s). The app answers every tool from the oldest protocol it supports; an older tool gets exit status 3 and the message to update it with Install Command Line Tool…. At launch TilingBud checks the tilingbud on your PATH and shows “Update the tilingbud command” in its welcome window when it no longer fits; a Homebrew installation is updated with brew upgrade.

Field names are fixed; indices are 1-based.

query --spaces: one object per space, ordered by display and position. type is the layout the space is arranged in, with the names space --layout takes (off, bsp, main, stacked), or fullscreen.

[{"display": 1, "focused": true, "id": 3, "index": 2, "label": "Mail", "position": 2, "type": "bsp", "visible": true, "windows": [4711, 815]}]

query --displays: one object per display that has spaces, ordered by index (the number display --focus takes and display in query --spaces). id is the window server’s display id, which changes when a display is plugged in again; uuid stays. spaces are the index of its spaces, frame is in points from the top left of the main display.

[{"focused": true, "frame": {"h": 982, "w": 1512, "x": 0, "y": 0}, "id": 1, "index": 1, "name": "Built-in Retina Display", "spaces": [1, 2, 3], "uuid": "37D8832A-2D66-02CA-B9F7-8F30A301B230"}]

subscribe: the connection stays open and every event comes as one line, with the values a signal gets (see “Signals” in configuration.md), for example {"event":"space_changed","recent_space_index":2,"space_id":42,"space_index":5,"display_id":"…","display_index":1}. Event names are those of [[signal]]; an unknown one fails with exit status 2. A bar listens this way instead of having a process started for every event; it runs nothing in the app and needs no [[signal]] entry.

query --rules: one object per [[rule]] in file order, with index (what rules --remove takes), line (of the header) and entries (the keys as written).

[{"entries": {"app": "Calculator", "float": true}, "index": 1, "line": 42}]

In rules --add, true, false and whole numbers are read as such, except_apps as a comma separated list (except_apps=Xcode,Safari), anything else as text; a value with blanks is quoted (app="Visual Studio Code"). The keys are those of [[rule]] in the configuration and are checked the same way: a bad entry fails and nothing is written.

query --windows: one object per window; space is the space’s id, frame is in points from the top left of the main display. state says where you can see the window: shown (on screen), minimized (in the Dock), appHidden (its app is hidden), hidesWithApp (its app shows it only while it is active, such as an update dialog: it is on no space meanwhile, no space lists it, and TilingBud moves it along to the space you are on) or otherSpace (on a space not shown). floating says whether the window’s space arranges it (false) or not (true); it is null where the space arranges nothing (layout off, full screen).

[{"app": "Mail", "floating": false, "focused": true, "frame": {"h": 800, "w": 1200, "x": 0, "y": 25}, "id": 4711,
"pid": 812, "space": 3, "state": "shown", "sticky": false, "title": "Inbox"}]

query --capabilities: one object per feature, with reason when it does not work and the user can change that (a permission, a macOS shortcut). How a feature works is not part of it.

{"windowMove": {"available": false, "reason": "Needs Accessibility access"}, "spaceManagement": {"available": false}}

query --shortcuts: the mode that is on (null for the shortcuts of [shortcuts]), the modes, and every shortcut with its keys as written, what it runs as written in the file (the steps of a list separated by ; ), its line and its mode.

{"mode": null, "modes": ["resize"], "shortcuts": [{"action": "app --open iTerm", "keys": "alt+return", "line": 12, "mode": null},
{"action": "window --resize west 50", "keys": "h", "line": 20, "mode": "resize"}]}

doctor: plain text for a support ticket: TilingBud’s version and build number, the macOS version and build, the SIP state, the macOS builds the release was tested on (with a line when the running build is not among them), per feature whether it works with a diagnostic code (how it works, or why not), the problems of the configuration file, and how fast TilingBud reacted to the latest events: the time from a change event to a placed new window, the snapshot read and the placement (median, 95th percentile, maximum) and the apps slowest to answer. The codes are listed in DiagnosticCode in the source and in the table “Diagnostic codes” of the workspace’s docs/macos-compatibility.md.

skhd (~/.config/skhd/skhdrc):

Terminal window
alt - 1 : tilingbud space --focus 1
shift + alt - 1 : tilingbud window --space 1 --follow
alt - n : tilingbud space --focus next
alt - b : tilingbud space --balance
alt - f : tilingbud space --raise-floating

Hammerspoon:

hs.hotkey.bind({"alt"}, "t", function() hs.execute("tilingbud space --tile", true) end)

Shell (with jq): the app of every window on the shown space.

Terminal window
space=$(tilingbud query --spaces | jq '.[] | select(.focused) | .id')
tilingbud query --windows | jq -r ".[] | select(.space == $space) | .app"

A bar or script that listens for events (with jq): the number of every space you switch to.

Terminal window
tilingbud subscribe space_changed | while read -r line; do
echo "$line" | jq .space_index
done

The app listens on the Unix socket /tmp/tilingbud_<user>.socket (TILINGBUD_SOCKET sets another path), created with mode 0600. The app accepts connections only from processes of the same user, replaces only a stale socket of its own, and the tool refuses a socket that belongs to another user. There is no network listener, and no command runs shell commands or reads or writes files other than the configuration file: a command can do what your own shortcuts can do (app --open starts an app as the Finder would). Shell commands (a shortcut value that is not a TilingBud command) exist only as shortcuts written in the configuration file; whatever arrives through the socket is parsed as a command and refused otherwise.