Command line
Diese Seite gibt es noch nicht auf Deutsch; hier steht die englische.
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.
Installing
Section titled “Installing”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
tilingbudinto/usr/local/binwhen it can write there, else into~/.local/binor~/binif that folder is on your shell’sPATH. -
Otherwise (on Apple silicon
/usr/local/binbelongs 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
tilingbudthat is already on thePATH, 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.
Commands
Section titled “Commands”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 thenameof 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
--displaycounts over all displays in Mission Control’s order (indexinquery --spaces): with ten spaces on the main display,space --focus 11is the first space of the second display, from whichever display. With--display <n|next|prev>(numbered asquery --spaceslists them indisplay) it counts on that display as Mission Control does, from 1 (position). nextandprevgo over the spaces of the active display (space --focus) or the window’s display (window --space), or of the display--displaynames; they skip full-screen spaces and do nothing at either end.
A space that is already shown on another display gets the focus there.
Spaces
Section titled “Spaces”tilingbud space --focus 3 # show space 3tilingbud space --focus next # the space to the right; also prevtilingbud space --focus 1 --display 2 # the first space of the second displaytilingbud space --focus recent # back to the space shown before; again to returntilingbud space --focus Finance # the space named Finance, on whichever display it istilingbud space --label Finance # name the shown space (its [[space]] name); space --label alone removes the nametilingbud space --create # add a space (Mission Control through Accessibility)tilingbud space --destroy 4 # remove space 4; without a number the shown spacetilingbud 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 overtilingbud 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 areatilingbud 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 alonetilingbud space --layout next # the next mode of [tiling] layout_cycle; also prevtilingbud space --layout recent # back to the mode the space had beforetilingbud 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]] layouttilingbud 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 ittilingbud 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-cleartilingbud space --layout-save # without a name: a window asks for the name and the choicestilingbud space --layout-choose # a window shows the saved layouts with their sketches; Return arranges # the shown space by the selected onetilingbud space --layout-clear # stop using the applied layout (also of space <index>): no waiting places, no floating others, no parkingtilingbud space --overview # every window of the space (or of space <index>) to scale, a scroll row at full length; click or Return goes to onetilingbud space --rotate 90 # turn the arrangement of the shown bsp space clockwise; also 180, 270tilingbud 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 -1tilingbud space --main-ratio +0.05 # a larger main area (0.1 to 0.9); also -0.05tilingbud 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 gapstilingbud space --toggle control-bar # show the shown space's control bar, or hide it, until [control_bar] show changestilingbud space --toggle show-desktop # move the windows aside to show the desktop, or bring them backtilingbud space --toggle mission-control # open Mission Control, or close ittilingbud space --inner-gap 7 --outer-gap 5 # points between the windows and at the edges of the shown spacetilingbud space --outer-gap +2 # 2 points more on every edge (-2: fewer); reset: the configured value againWindows
Section titled “Windows”tilingbud window --space 3 # move the focused window to space 3tilingbud window --space 3 --follow # ... and show space 3 with the window focusedtilingbud window --space next --no-follow # ... and stay, whatever the configured default saystilingbud window --space 2 --app # move all windows of the focused window's apptilingbud 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 displaytilingbud window --display next # to the space shown on the next display; also prev, recent or a numbertilingbud 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 = truetilingbud window --toggle float --id 4711 # the same for window 4711tilingbud window --toggle all-spaces # the focused window's app on every space, or back on the shown space only; a window on all spaces floatstilingbud window --toggle all-spaces --id 4711 # the same for the app of window 4711tilingbud window --toggle float --grid 29:4:1:1:2:27 # and put it in the middle half when it floats nowtilingbud window --menu # the window menu at the focused window: spaces, float, layout, ruletilingbud window --focus 4711 # focus window 4711, showing its spacetilingbud window --focus west # focus the nearest window to the west; also east, north, southtilingbud window --swap east # exchange places with the arranged window to the easttilingbud 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 inwardstilingbud 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.05tilingbud window --ratio next # the next share of [tiling] ratio_steps (½, ⅔, ⅓), from the step nearest to the share now; prev goes backtilingbud window --insert south # the next new window goes below this one (bsp); the same again clears ittilingbud 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 bsptilingbud window --focus stack.next # the next window of a stacked space or of the window's stack (bsp), wrapping around; also stack.prevtilingbud window --stack west # put the window into the cell of the window to the west, first in its stack (bsp); also a window idtilingbud window --unstack # take the window out of its stack into a cell of its own beside ittilingbud window --focus east # scroll: the window of the next column, scrolled into view; north, south within the columntilingbud window --swap west # scroll: exchange the focused column with the one to the westtilingbud window --warp west # scroll: put the window at the bottom of the column to the westtilingbud window --unstack # scroll: take the window out of its column into a column of its own right of ittilingbud window --stack west # scroll: put the window into the column to the west as a tab; stack.next and stack.prev go through the tabstilingbud window --ratio 1 # scroll: the focused column as wide as the screen (0.1 to 1); also +0.1, -0.1tilingbud window --ratio next # scroll: the next width of [tiling] scroll_widths (½, ⅔, full); prev goes backtilingbud window --center # scroll: put the focused column in the middle of the screen oncetilingbud window --resize south 100 # scroll: 100 points more height for the window, from the one below it; east, west: the column's widthtilingbud window --height next # scroll: the next share of [tiling] scroll_heights for a window sharing its column; also 0.6, +0.1, prevtilingbud space --balance # scroll: every column as wide as the focused one, equal heights in each columntilingbud window --focus floating.next # the next floating window of the space in focus order, brought forward; also floating.prevtilingbud window --focus recent # the window that had the focus before this one on its spacetilingbud window --focus next # the next arranged window in reading order, wrapping; also prev, first, lasttilingbud window --focus index:3 # the third window of the space as the control bar lists it; in scroll the third columntilingbud window --focus mouse # the window under the pointertilingbud window --label term # name the focused window for this session; --focus, --swap and --warp take the nametilingbud window --focus term # focus the window labeled term, showing its space; window --label alone removes the labeltilingbud window --swap recent # swap and warp take the same window choices as --focustilingbud window --toggle zoom-fullscreen # cover the whole space, the layout stays behind; again to go backtilingbud window --toggle zoom-parent # cover the area the window shares with its neighbor in the layouttilingbud 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 4711tilingbud window --toggle expose # App Exposé of the app in front, or close ittilingbud 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 spacetilingbud window --move 40 -20 # a floating window 40 points right and 20 uptilingbud window --close # close the focused window as its close button does; also --id 4711tilingbud window --minimize # into the Dock; also --id 4711tilingbud 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.
--focusby 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. --insertmarks 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-countand--main-ratiohold for that space until TilingBud restarts, like a divider dragged with the mouse; the defaults are[tiling] main_countandmain_ratio.--grid,--center,--moveand--resizeplace windows the layout does not arrange (floating windows, windows onoffspaces) inside the usable area of their space;--grid,--centerand--moverefuse an arranged window, and--resizemoves its edge in the layout instead.
Displays
Section titled “Displays”tilingbud display --focus next # the last active window of the next display, or its shown spacetilingbud display --focus recent # back to the display that had the focus beforetilingbud display --focus 2 # display 2, numbered as query --spaces lists them in displayWith 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.
For shortcuts: apps, keys and modes
Section titled “For shortcuts: apps, keys and modes”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.
tilingbud app --open iTerm # start iTerm, or bring it to the front with its spacetilingbud app --open com.apple.Safari --url https://example.com # a bundle identifier; open the link in ittilingbud app --open com.microsoft.VSCode --file ~/notes.md # open the file in the apptilingbud app --open Terminal --new --args -v # another instance, started with these argumentstilingbud 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.
Queries
Section titled “Queries”tilingbud query --spaces # all spaces as JSONtilingbud query --spaces index,label # only these fields of each spacetilingbud query --displays # the displays with their spaces as JSONtilingbud query --windows # all windows as JSONtilingbud query --windows id,app,floating # only these fields of each windowtilingbud query --windows --space 2 # windows of space 2 and the windows shown on every spacetilingbud query --windows --all # also app windows on another level, which TilingBud leaves alone (with "level")tilingbud query --capabilities # which features work on this Mactilingbud query --shortcuts # the shortcuts of [shortcuts] and of every mode, and the mode that is ontilingbud query --rules # the window rules with their index, line and keystilingbud 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 eventtilingbud query --window # what TilingBud sees of the focused window, and why it is tiled or nottilingbud query --window 4711 # the same for window 4711tilingbud help # every command with its flags; the same without argumentstilingbud window --help # the flags of one domaintilingbud doctor # a report to attach to a support tickettilingbud 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 RelaunchFields 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.
Maintenance
Section titled “Maintenance”tilingbud config --reload # read the configuration file nowtilingbud rules --apply # apply the window rules to every open windowtilingbud rules --add app=Calculator float=true # write a [[rule]] with these keys and apply the rulestilingbud 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 apptilingbud refresh # read spaces and windows againtilingbud settings # open the Settings window (also while the menu bar item is hidden)Output and exit status
Section titled “Output and exit status”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) |
Tool and app versions
Section titled “Tool and app versions”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.
Examples
Section titled “Examples”skhd (~/.config/skhd/skhdrc):
alt - 1 : tilingbud space --focus 1shift + alt - 1 : tilingbud window --space 1 --followalt - n : tilingbud space --focus nextalt - b : tilingbud space --balancealt - f : tilingbud space --raise-floatingHammerspoon:
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.
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.
tilingbud subscribe space_changed | while read -r line; do echo "$line" | jq .space_indexdoneSecurity
Section titled “Security”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.