AeroSpace is an i3-like tiling window manager for macOS

Project homepage: https://github.com/nikitabobko/AeroSpace

300

1. close

close [-h|--help] [--quit-if-last-window]

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

OPTIONS

-h, --help

Print help

--quit-if-last-window

Quit the app instead of closing if it’s the last window of the app

2. close-all-windows-but-current

close-all-windows-but-current [-h|--help] [--quit-if-last-window]

On the focused workspace, close all windows but current

OPTIONS

-h, --help

Print help

--quit-if-last-window

Quit the apps instead of closing them if it’s their last window

3. enable

enable [-h|--help] (on|off|toggle)

Temporarily disable window management

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

Key events are not intercepted when AeroSpace is disabled

4. exec-and-forget

exec-and-forget <bash-script>

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:

alt-enter = 'exec-and-forget open -n /System/Applications/Utilities/Terminal.app'

<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 command is available in config

  • The command is NOT available in CLI

5. flatten-workspace-tree

flatten-workspace-tree [-h|--help]

Flatten the tree of currently focused workspace.

The command is useful when you messed up with your layout, and it’s easier to "reset" it and start again.

6. focus

focus [-h|--help] [--boundaries <boundary>]
      [--boundaries-action <action>] (left|down|up|right)
focus [-h|--help] --window-id <window-id>

Set focus to the nearest window in in the given direction.

Contrary to i3, focus command doesn’t have a separate argument to focus floating windows. From focus command perspective, floating windows are part of the tree. The floating window parent container is determined as the smallest tiling container that contains the center of the floating window.

This technique eliminates the need for an additional binding for floating windows.

focus child|parent isn’t supported because the necessity of this operation is under the question. https://github.com/nikitabobko/AeroSpace/issues/5

OPTIONS

-h, --help

Print help

--boundaries <boundary>

Defines focus boundaries.
<boundary> possible values: (workspace|all-monitors-outer-frame).
The default is: workspace

--boundaries-action <action>

Defines the behavior when requested to cross the <boundary>.
<action> possible values: (stop|wrap-around-the-workspace|wrap-around-all-monitors)
The default is: wrap-around-the-workspace

--window-id <window-id>

Focus the window with specified <window-id>

7. focus-monitor

focus-monitor [-h|--help] [--wrap-around] (left|down|up|right)
focus-monitor [-h|--help] [--wrap-around] (next|prev)
focus-monitor [-h|--help] <monitor-pattern>...

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

OPTIONS

-h, --help

Print help

--wrap-around

Make it possible to wrap around focus

ARGUMENTS

(left|down|up|right)

Focus monitor in direction relative to the currently focused monitor

(next|prev)

Focus next|prev monitor in order they appear in tray icon

<monitor-pattern>

Find the first monitor pattern in the list that doesn’t describe the current monitor and focus it. Monitor pattern is the same as in workspace-to-monitor-force-assignment config option

8. fullscreen

fullscreen [-h|--help] [on|off]

Toggle the fullscreen mode for the currently 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.

OPTIONS

-h, --help

Print help

ARGUMENTS

[on|off]

on means enter fullscreen mode. off means exit fullscreen mode. Toggle between the two if not specified

9. join-with

join-with [-h|--help] (left|down|up|right)

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

EXAMPLES

Given this layout

h_tiles
├── window 1
├── window 2 (focused)
└── window 3

join-with right will result in the following layout

h_tiles
├── window 1
└── v_tiles
    ├── window 2 (focused)
    └── window 3
Note
 join-with is a high-level replacement for i3’s split command. There is an observation that the only reason why you might want to split a node is to put several windows under a common "umbrella" parent. Unlike split, join-with can be used with enable-normalization-flatten-containers

10. layout

layout [-h|--help] (h_tiles|v_tiles|h_accordion|v_accordion|tiles|accordion|horizontal|vertical|tiling|floating)...

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.

  • Change both tiling layout and orientation in one go: h_tiles|v_tiles|h_accordion|v_accordion

  • Change tiling layout but preserve orientation: tiles|accordion

  • Change orientation but preserve layout: horizontal|vertical

  • Toggle floating/tiling mode: tiling|floating

11. macos-native-fullscreen

macos-native-fullscreen [-h|--help] [on|off]

Toggle macOS fullscreen for the currently focused window

OPTIONS

-h, --help

Print help

ARGUMENTS

[on|off]

on means enter fullscreen mode. off means exit fullscreen mode. Toggle between the two if not specified

12. macos-native-minimize

macos-native-minimize [-h|--help]

Toggle macOS minimize for the currently focused window

13. mode

mode [-h|--help] <binding-mode>

Activate the specified binding mode

See the guide for documentation about binding modes

14. move

move [-h|--help] (left|down|up|right) [floating_pixel]

Move the window in the given direction

The optional floating_pixel argument specifies how far the window should be moved if it is floating. The default is 50 pixels

Deprecated name: move-through

EXAMPLES

  1. Given this layout

    h_tiles
├── window 1 (focused)
└── window 2

    move right will result in the following layout

    h_tiles
├── window 2
└── window 1 (focused)

  2. Given this layout

    h_tiles
├── window 1
├── window 2 (focused)
└── v_tiles
    ├── window 3
    └── window 4

    move right will result in the following layout

    h_tiles
├── window 1
└── v_tiles
    ├── window 3
    ├── window 2 (focused)
    └── window 4

  3. Given this layout

    h_tiles
├── window 1
└── v_tiles
    ├── window 3
    ├── window 2 (focused)
    └── window 4

    move left will result in the following layout

    h_tiles
├── window 1
├── window 2 (focused)
└── v_tiles
    ├── window 3
    └── window 4

  4. Implicit container example

    In some cases, move needs to implicitly create a container to fulfill your command.

    Given this layout

    h_tiles
├── window 1
├── window 2 (focused)
└── window 3

    move up will result in the following layout

    v_tiles
├── window 2 (focused)
└── h_tiles
    ├── window 1
    └── window 3

    v_tiles is an implicitly created container.

15. move-node-to-monitor

move-node-to-monitor [-h|--help] [--wrap-around] (left|down|up|right)
move-node-to-monitor [-h|--help] [--wrap-around] (next|prev)
move-node-to-monitor [-h|--help] <monitor-pattern>...

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

OPTIONS

-h, --help

Print help

--wrap-around

Make it possible to wrap around the movement

ARGUMENTS

(left|down|up|right)

Move window to monitor in direction relative to the currently focused monitor

(next|prev)

Move window to next|prev monitor in order they appear in tray icon

<monitor-pattern>

Find the first monitor pattern in the list that doesn’t describe the current monitor and move the window to the appropriate monitor. Monitor pattern is the same as in workspace-to-monitor-force-assignment config option

16. move-node-to-workspace

move-node-to-workspace [-h|--help] [--wrap-around] (next|prev)
move-node-to-workspace [-h|--help] <workspace-name>

Move currently focused window to the specified workspace

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

OPTIONS

-h, --help

Print help

--wrap-around

Make it possible to jump between first and last workspaces using (next|prev)

17. move-workspace-to-monitor

move-workspace-to-monitor [-h|--help] --wrap-around (next|prev)

Move currently focused workspace to the next or previous monitor

The command doesn’t have effect on workspaces that have monitor assignment

OPTIONS

-h, --help

Print help

--wrap-around

Allows to move workspace between first and last monitors

18. reload-config

reload-config [-h|--help]

Reload currently active config

Reloading the config changes active binding mode to "main"

19. resize

resize [-h|--help] (smart|width|height) [+|-]<number>

Resize the currently focused window

The dimension to resize is chosen by the first argument

  • width changes width

  • height changes height

  • smart changes width if the parent has horizontal orientation, and it changes height if the parent has vertical orientation

Second argument controls how much the size is changes

  • If the <number> is prefixed with + then the dimension is increased

  • If the <number> is prefixed with - then the dimension is decreased

  • If the <number> is prefixed with neither + nor - then the command changes the absolute value of the dimension

20. split

split [-h|--help] (horizontal|vertical|opposite)

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

  1. Creates a new tiling container

  2. Replaces currently focused window with the container

  3. Puts the currently focused window into the container as its the only child

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

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

Important
 split command has no effect if enable-normalization-flatten-containers is turned on. Consider using join-with if you want to keep enable-normalization-flatten-containers enabled

21. workspace

workspace [-h|--help] [--wrap-around] (next|prev)
workspace [-h|--help] [--auto-back-and-forth] <workspace-name>

1. <workspace-name> syntax

Focus the specified workspace

2. (next|prev) syntax

Focuses next or previous workspace in the list.

  • If stdin is not TTY and stdin contains non whitespace characters then the list is taken from stdin

  • Otherwise, the list is defined as all workspaces on focused monitor in alphabetical order

OPTIONS

-h, --help

Print help

--auto-back-and-forth

Automatic back-and-forth when switching to already focused workspace

--wrap-around

Make it possible to jump between first and last workspaces using (next|prev)

22. workspace-back-and-forth

workspace-back-and-forth [-h|--help]

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

23. Query commands

Query commands are commands that do not change the state but rather allow the examination of the current state.

  • Query commands are NOT available in config
    (because there is no way to consume the stdout of these commands in config)

  • Query commands are only available in CLI

23.1. debug-windows

debug-windows [-h|--help]

Interactive command to record Accessibility API debug information to create bug reports

Use this command output to report bug reports about incorrect windows handling (e.g. some windows are floated when they shouldn’t).

The intended usage is the following:

  1. Run the command to start the debug session recording

  2. Focus problematic window

  3. Run the command one more time to stop the debug session recording and print the results

debug-windows command is not stable API. Please don’t rely on the command existence and output format. The only intended use case is to report bugs about incorrect windows handling.

23.2. list-apps

list-apps [-h|--help] [--macos-native-hidden [no]]

Print the list of running applications that appears in the Dock and may have a user interface

The command is useful to inspect list of applications to compose filter for on-window-detected callback

OUTPUT FORMAT

Output format is the table with the following columns:

  • Process ID

  • Application ID

  • Application name

Output example:

486   | com.apple.finder            | Finder
17966 | org.alacritty               | Alacritty
24780 | com.jetbrains.AppCode       | AppCode
32541 | com.apple.systempreferences | System Settings

You can use awk to get values of particular column: awk -F '|' '{print $2}'

OPTIONS

-h, --help

Print help

--macos-native-hidden [no]

Filter results to only print hidden applications. [no] inverts the condition

23.3. list-exec-env-vars

list-exec-env-vars [-h|--help]

List environment variables that exec-* commands and callbacks are run with

Examples of commands and callbacks:

  • aerospace exec-and-forget command

  • exec-on-workspace-change-callback

23.4. list-monitors

list-monitors [-h|--help] [--focused [no]] [--mouse [no]]

Print monitors that satisfy conditions

OUTPUT FORMAT

Output format is the table with 2 columns:

  • Monitor unique sequence ID (ID orders monitors from left to right)

  • Monitor name

Output example:

1 | Built-in Retina Display
2 | DELL U2723QE
Note
 monitor sequence ID may change if you plug or unplug monitors

You can use awk to get values of particular column: awk -F '|' '{print $2}'

OPTIONS

-h, --help

Print help

--focused [no]

Filter results to only print the focused monitor. [no] inverts the condition

--mouse [no]

Filter results to only print the monitor with the mouse. [no] inverts the condition

23.5. list-windows

list-windows [-h|--help] (--workspace <workspace>...|--monitor <monitor>...)
             [--monitor <monitor>...] [--workspace <workspace>...]
             [--pid <pid>] [--app-id <app-id>] [--macos-native-hidden-app [no]]
             [--macos-native-minimized] [--macos-native-fullscreen]
list-windows [-h|--help] --all
list-windows [-h|--help] --focused

Print windows that satisfy conditions

OUTPUT FORMAT

Output format is table with three columns:

  1. Window ID

  2. App name

  3. Window title

Output Example:

5010 | AppCode   | AeroSpace – aerospace-list-windows.adoc
5360 | AppCode   | Git - AeroSpace
2412 | Alacritty | /Users/bobko $ ta
5046 | Xcode     | AeroSpace — ListWorkspacesCommand.swift

OPTIONS

-h, --help

Print help

--all

Alias for --monitor all. Please use this option with cautious. Use it when you really need to get workspaces/windows from all monitors.

For multi-monitor setup --monitor focused is almost always a preferred option. If you’re automating something then you don’t want to mess up with workspaces/windows on a different monitor.

With great power comes great responsibility.

--focused

Print the focused window. Please note that it is possible for no window to be in focus. In that case, error is reported.

--workspace <workspaces>

Filter results to only print windows that belong to specified workspaces. <workspaces> is a comma-separated list of workspace names.

Possible values:

  1. Workspace name

  2. visible is a special workspace name that represents currently visible workspaces

  3. focused is a special workspace name that represents currently focused workspace

--monitor <monitors>

Filter results to only print workspaces/windows that are attached to specified monitors. <monitors> is a space separated list of monitor IDs.

Possible monitors IDs:

  1. 1-based index of a monitor as if monitors were ordered horizontally from left to right

  2. all is a special monitor ID that represents all monitors

  3. mouse is a special monitor ID that represents monitor with the mouse

  4. focused is a special monitor ID that represents currently focused monitor

--pid <pid>

Filter results to only print windows that belong to the Application with specified <pid>

--app-id <app-id>

Filter results to only print windows that belong to the Application with specified Bundle ID

--macos-native-hidden-app [no]

Filter results to only print windows that belong to hidden applications. [no] inverts the condition

--macos-native-minimized [no]

Filter results to only print minimized windows. [no] inverts the condition

--macos-native-fullscreen [no]

Filter results to only print fullscreen windows. [no] inverts the condition

23.6. list-workspaces

list-workspaces [-h|--help] --monitor <monitor>... [--visible [no]] [--empty [no]]
list-workspaces [-h|--help] --all
list-workspaces [-h|--help] --focused

Print workspaces that satisfy conditions

OPTIONS

-h, --help

Print help

--all

Alias for --monitor all. Please use this option with cautious. Use it when you really need to get workspaces/windows from all monitors.

For multi-monitor setup --monitor focused is almost always a preferred option. If you’re automating something then you don’t want to mess up with workspaces/windows on a different monitor.

With great power comes great responsibility.

--focused

Alias for "--monitor focused --visible". Always prints a single workspace

--monitor <monitors>

Filter results to only print workspaces/windows that are attached to specified monitors. <monitors> is a space separated list of monitor IDs.

Possible monitors IDs:

  1. 1-based index of a monitor as if monitors were ordered horizontally from left to right

  2. all is a special monitor ID that represents all monitors

  3. mouse is a special monitor ID that represents monitor with the mouse

  4. focused is a special monitor ID that represents currently focused monitor

--visible [no]

Filter results to only print currently visible workspaces. [no] inverts the condition. Several workspaces can be visible in multi-monitor setup

--empty [no]

Filter results to only print empty workspaces. [no] inverts the condition.