AeroSpork Commands

Balance sizes of all windows in the current workspace

Close the focused window

Normally, you don’t need to use this command, because macOS offers its own cmd+w binding. You might want to use the command from CLI for scripting purposes

On the focused workspace, close all windows but current

Temporarily disable window management

When you disable AeroSpork, windows from currently invisible workspaces will be placed to the visible area of the screen

Key events are not intercepted when AeroSpork is disabled

While disabled, the server rejects every other command — including query commands — with a non-zero exit code and the message "server is disabled and doesn’t accept commands". aerospork enable on|off|toggle is the one exception. -h|--help and -v|--version still work because the CLI answers them without contacting the server

Run /bin/bash -c '<bash-script>', and don’t wait for the command termination. Stdout, stderr and exit code are ignored.

For example, you can use this command to launch applications:

<bash-script> is passed "as is" to bash without any transformations and escaping. <bash-script> is treated as suffix of the TOML string, it’s not even an argument in classic CLI sense

The script inherits AeroSpork’s full environment, including any secrets in it: API tokens, credentials, anything exported by your shell profile at launch. This is deliberate, since a script that posts to Slack needs its token. But it means the config file is trusted input.

Treat an exec-and-forget line copied from the internet exactly as you would treat a line you were about to paste into your shell.

aerospork list-exec-env-vars redacts secret-looking values by default when displaying them; that is a shoulder-surfing guard only and does not change what the child process receives. Use --show-secrets to see the real values.

AeroSpork adds, when the command has a target, AEROSPORK_WINDOW_ID or AEROSPORK_WORKSPACE; and for commands run by on-focused-workspace-changed, AEROSPORK_FOCUSED_WORKSPACE and AEROSPORK_PREV_WORKSPACE.

Set [exec] inherit-env-vars = false to start from an empty environment, and [exec] env-vars to declare exactly what should be passed through.

Flatten the tree of the focused workspace

Use it when resetting a layout is quicker than repairing it by hand.

Set focus to the nearest window in the given direction

Unlike i3, focus has no separate argument for floating windows. It treats them as part of the tree, which removes the need for a separate binding. Pass --ignore-floating to turn that off.

focus child|parent is not supported.

Switch between the current and previously focused elements back and forth. The element is either a window or an empty workspace.

AeroSpork stores only one previously focused window in history, which means that if you close the previous window, focus-back-and-forth has no window to switch focus to. In that case, the command will exit with non-zero exit code.

That’s why it may be preferred to combine focus-back-and-forth with workspace-back-and-forth:

Also see: workspace-back-and-forth

Focus monitor by relative direction, by order, or by pattern

Toggle the fullscreen mode for the focused window

Switching to a different tiling window within the same workspace while the current focused window is in fullscreen mode results in the fullscreen window exiting fullscreen mode.

Put the focused window and the nearest node in the specified direction under a common parent container

Given this layout

join-with right will result in the following layout

Change layout of the focused window to the given layout

If several arguments are supplied then finds the first argument that doesn’t describe the currently active layout, and applies the layout.

Deprecated (but still supported) layout names: list, h_list, v_list for tiles, h_tiles, v_tiles

Toggle macOS fullscreen for the focused window

Minimize focused window

Activate the specified binding mode

See the guide for documentation about binding modes

Move the focused window in the given direction. See the "Examples" section for more details.

Deprecated name: move-through

Move mouse to the requested position

When no window is focused, which is the case on an empty workspace, both window-* values fall back to the focused monitor. Centering on "the focused window" has no meaning there, and the alternative is leaving the pointer on the monitor you switched away from. This matters most in on-focused-workspace-changed, where a callback is a list of commands and cannot express the shell fallback below.

Move window to monitor targeted by relative direction, by order, or by pattern

Move the focused window to the specified workspace

(next|prev) is identical to workspace (next|prev)

Move workspace to monitor targeted by relative direction, by order, or by pattern. Focus follows the workspace, so the workspace stays focused.

Deprecated name: move-workspace-to-display

The command fails for a workspace that has a monitor force assignment.

Open the settings window

Equivalent to choosing Settings… from the menu bar icon, pressing kbd:[Cmd+,] while AeroSpork is frontmost, or opening AeroSpork again (from Finder, Spotlight or open -a AeroSpork) while it is running. The settings window is a singleton: running this while it is already open brings the existing window to the front. The window comes to the front even when another app is frontmost, and AeroSpork never tiles it or moves it to a workspace.

The command is allowed in config, so it can be bound to a key:

The window has seven panes: General, Gaps, Keys, Monitors, Events, Window Rules, and Raw TOML. It is resizable (opens at 880×620, minimum 780×520) and remembers its selected pane.

Structured settings apply live as you change them, and a change still pending when you close the window is saved. The Raw TOML pane is the exception: it applies explicitly, so half-typed TOML is never written. Raw TOML supports native Find, line numbers, section jumps, and parser errors that link to the failing line.

A complex badge marks a value richer than the structured controls can edit. Such a value is preserved on save, and can be edited in Raw TOML.

Reload currently active config

If the config contains errors, they are printed to stdout and the GUI opens to show them.

Resize the focused window

The first argument chooses the dimension to resize

The second argument controls how much the size changes

resize on a floating window is not supported yet.

split exists solely for compatibility with i3. Prefer join-with unless you have a specific reason not to.

If the parent of focused window contains more than one child, then the command

The argument sets the orientation of the newly created container. opposite means the opposite orientation to the parent container.

If the parent of the focused window contains only a single child (the window itself), split changes the orientation of the parent container

Move the requested workspace to the focused monitor. The moved workspace becomes focused. The behavior is identical to Xmonad’s.

The command is only meaningful in a multi-monitor setup. On a single monitor it is identical to workspace.

Trigger AeroSpork binding as if it was pressed by user

Inspect the available bindings with aerospork config:
aerospork config --get mode.main.binding --keys

Manipulate volume

1. <workspace-name> syntax

Focus the specified workspace

2. (next|prev) syntax

Focuses next or previous workspace in the list.

Workspace lifecycle

A workspace the config declares always exists, even while it is empty: every name in workspaces, every name in persistent-workspaces, and every workspace pinned to a monitor. aerospork list-workspaces --all, the menu bar and workspace next/prev show all of them.

Any other workspace, such as one that only a keybinding of your own mentions, is created the first time you switch to it and released once it is empty and no longer visible. It costs nothing until you use it: switching back recreates it indistinguishably, because an empty workspace is nothing but its name.

Switch between the focused workspace and previously focused workspace back and forth

Unlike focus-back-and-forth, workspace-back-and-forth always succeeds. Because unlike windows, workspaces can not be "closed". Workspaces are name-addressable objects. They are created and destroyed on the fly.

Also see: focus-back-and-forth

Query commands examine the current state without changing it.

~/.aerospork.toml or ${XDG_CONFIG_HOME}/aerospork/aerospork.toml (XDG_CONFIG_HOME falls back to ~/.config when the variable is not set); a debug build uses ~/.aerospork-debug.toml. If a config is found in more than one location, the ambiguity is reported. A complete config: