AeroSpace is an i3-like tiling window manager for macOS

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

300

Commands documentation is also available in the form of manpages.

1. balance-sizes

aerospace balance-sizes [-h|--help]

Balance sizes of all windows in the current workspace

2. close

aerospace 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

3. close-all-windows-but-current

aerospace 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

4. enable

aerospace 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

5. exec-and-forget

aerospace 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

6. flatten-workspace-tree

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

Flatten the tree of the focused workspace

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

7. focus

aerospace focus [-h|--help] [--boundaries <boundary>]
                [--boundaries-action <action>] [--ignore-floating] (left|down|up|right)
aerospace 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. The technique eliminates the need for an additional binding for floating windows. This behavior can be disabled with --ignore-floating flag.

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>

--ignore-floating

Don’t perceive floating windows as part of the tree. It may be useful for more reliable scripting.

8. focus-back-and-forth

aerospace focus-back-and-forth [-h|--help]

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

AeroSpace 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:

aerospace focus-back-and-forth || aerospace workspace-back-and-forth

Also see: workspace-back-and-forth

9. focus-monitor

aerospace focus-monitor [-h|--help] [--wrap-around] (left|down|up|right)
aerospace focus-monitor [-h|--help] [--wrap-around] (next|prev)
aerospace 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 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

10. fullscreen

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

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.

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

11. join-with

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

Put the 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

12. layout

aerospace 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

OPTIONS

-h, --help

Print help

EXAMPLES

  • Toggle between floating and tiling layouts (order of args doesn’t matter):
    aerospace layout floating tiling

  • Toggle orientation (order of args doesn’t matter):
    aerospace layout horizontal vertical

  • Toggle between tiles and accordion layouts (order of args doesn’t matter):
    aerospace layout tiles accordion

  • Switch to tiles layout. Toggle the layout orientation if already in tiles layout:
    aerospace layout tiles horizontal vertical

13. macos-native-fullscreen

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

Toggle macOS fullscreen for the 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

14. macos-native-minimize

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

Toggle macOS minimize for the focused window

15. mode

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

Activate the specified binding mode

See the guide for documentation about binding modes

16. move

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

Move the window in the given direction

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.

17. move-mouse

aerospace move-mouse [-h|--help] <mouse-position>

Move mouse to the requested position

OPTIONS

-h, --help

Print help

ARGUMENTS

<mouse-position>

Position to move mouse to. Possible values:

  • monitor-lazy-center. Move mouse to the center of the focused monitor, unless it is already within the monitor boundaries.

  • monitor-force-center. Move mouse to the center of the focused monitor.

  • window-lazy-center. Move mouse to the center of the focused window, unless it is already within the window boundaries. Fails the command if no window is focused.

  • window-force-center. Move mouse to the center of the focused window. Fails the command if no window is focused.

EXAMPLES

  • Try to move mouse to the center of the window. If there is no window in focus, move mouse to the center of the monitor:
    aerospace move-mouse window-lazy-center || aerospace move-mouse monitor-lazy-center

18. move-node-to-monitor

aerospace move-node-to-monitor [-h|--help] [--wrap-around] (left|down|up|right)
aerospace move-node-to-monitor [-h|--help] [--wrap-around] (next|prev)
aerospace 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 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

19. move-node-to-workspace

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

Move the 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)

20. move-workspace-to-monitor

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

Move the 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

21. reload-config

aerospace reload-config [-h|--help] [--no-gui] [--dry-run]

Reload currently active config

If the config contains errors they will be printed to stdout, and GUI will open to show the errors.

OPTIONS

-h, --help

Print help

--no-gui

Don’t open GUI to show error. Only use stdout to report errors

--dry-run

Validate the config and show errors (if any) but don’t reload the config

EXIT CODE

0

Success. The config is reloaded successfully.

non-zero exit code

Failure. The config contains errors.

22. resize

aerospace 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

23. split

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

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

  1. Creates a new tiling container

  2. Replaces the focused window with the container

  3. Puts the 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 the 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

24. trigger-binding

aerospace trigger-binding [-h|--help] <binding> --mode <mode-id>

Trigger AeroSpace binding as if it was pressed by user

You can use aerospace-config command to inspect available bindings:
aerospace config --get mode.main.binding --keys

OPTIONS

-h, --help

Print help

--mode <mode-id>

Mode to search <binding> in

ARGUMENTS

<binding>

Binding to trigger

EXAMPLES

  • Run alphabetically first binding from config (useless and synthetic example):
    aerospace trigger-binding --mode main "$(aerospace config --get mode.main.binding --keys | head -1)"

  • Trigger alt-tab binding:
    aerospace trigger-binding --mode main alt-tab

25. workspace

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

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)

EXAMPLES

  • Go to the next non empty workspace on the focused monitor:
    aerospace list-workspaces --monitor focused --empty no | aerospace workspace next

26. workspace-back-and-forth

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

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

27. 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

27.1. config

aerospace config [-h|--help] --get <name> [--json] [--keys]
aerospace config [-h|--help] --major-keys
aerospace config [-h|--help] --all-keys
aerospace config [-h|--help] --config-path

Query AeroSpace config options

For now, only mode.* config options are supported

Under the hood, the config is represented as recursive data structure of maps, arrays, strings, and integers.

Printing without --json or --keys flag is supported only for scalar types (strings and integers) and array of scalar types. Printing other complicated objects requires --json or --keys flag.

OPTIONS

-h, --help

Print help

--get <name>

Get the value for a given key. You can inspect available keys with --major-keys or --all-keys

--major-keys

Print major keys

--all-keys

Print all available keys recursively

--json

Print result in JSON format

--keys

Print keys of the complicated object (map or array)

--config-path

Print absolute path to the loaded config

EXAMPLES

  • List all binding modes:

    $ aerospace config --get mode --keys
main
service

  • List all key bindings for 'main' binding mode:

    $ aerospace config --get mode.main.binding --keys
alt-1
alt-2
...

  • List all key bindings for 'main' binding mode in JSON format:

    $ aerospace config --get mode.main.binding --json
{
  "alt-shift-5" : [
    "move-node-to-workspace 5"
  ],
  "alt-r" : [
    "workspace R"
  ],
  "alt-shift-6" : [
    "move-node-to-workspace 6"
  ],
...

27.2. debug-windows

aerospace 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.

27.3. list-apps

aerospace list-apps [-h|--help] [--macos-native-hidden [no]] [--format <output-format>]

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

OPTIONS

-h, --help

Print help

--macos-native-hidden [no]

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

--format <output-format>

Specify output format. See "Output Format" section for more details

OUTPUT FORMAT

Output format can be configured with optional [--format <output-format>] option. <output-format> supports string interpolation.

If not specified, the default <output-format> is:
%{app-pid}%{right-padding} | %{app-bundle-id}%{right-padding} | %{app-name}

The following variables can be used inside <output-format>:

%{app-bundle-id}

String. Application unique identifier. Bundle ID

%{app-name}

String. Application name

%{app-pid}

Number. UNIX process identifier

%{right-padding}

A special variable which expands with a minimum number of spaces required to form a right padding in the appropriate column

%{newline}

Unicode U+000A newline symbol \n

%{tab}

Unicode U+0009 tab symbol \t

27.4. list-exec-env-vars

aerospace 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

27.5. list-monitors

aerospace list-monitors [-h|--help] [--focused [no]] [--mouse [no]] [--format <output-format>]

Print monitors that satisfy conditions

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

--format <output-format>

Specify output format. See "Output Format" section for more details

OUTPUT FORMAT

Output format can be configured with optional [--format <output-format>] option. <output-format> supports string interpolation.

If not specified, the default <output-format> is:
%{monitor-id}%{right-padding} | %{monitor-name}

The following variables can be used inside <output-format>:

%{monitor-id}

Number. Sequential number of the belonging monitor

%{monitor-name}

String. Name of the belonging monitor

%{right-padding}

A special variable which expands with a minimum number of spaces required to form a right padding in the appropriate column

%{newline}

Unicode U+000A newline symbol \n

%{tab}

Unicode U+0009 tab symbol \t

27.6. list-windows

aerospace list-windows [-h|--help] (--workspace <workspace>...|--monitor <monitor>...)
                       [--monitor <monitor>...] [--workspace <workspace>...]
                       [--pid <pid>] [--app-bundle-id <app-bundle-id>] [--format <output-format>]
aerospace list-windows [-h|--help] --all [--format <output-format>]
aerospace list-windows [-h|--help] --focused [--format <output-format>]

Print windows 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

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

--workspace <workspace>…​

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

Possible values:

  1. Workspace name

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

  3. focused is a special workspace name that represents the 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 the focused monitor

--pid <pid>

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

--app-bundle-id <app-bundle-id>

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

Deprecated (but still supported) flag name: --app-id

--format <output-format>

Specify output format. See "Output Format" section for more details

OUTPUT FORMAT

Output format can be configured with optional [--format <output-format>] option. <output-format> supports string interpolation.

If not specified, the default <output-format> is:
%{window-id}%{right-padding} | %{app-name}%{right-padding} | %{window-title}

The following variables can be used inside <output-format>:

%{window-id}

Number. Window unique ID

%{window-title}

String. Window title

%{app-bundle-id}

String. Application unique identifier. Bundle ID

%{app-name}

String. Application name

%{app-pid}

Number. UNIX process identifier

%{workspace}

String. Name of the belonging workspace

%{monitor-id}

Number. Sequential number of the belonging monitor

%{monitor-name}

String. Name of the belonging monitor

%{right-padding}

A special variable which expands with a minimum number of spaces required to form a right padding in the appropriate column

%{newline}

Unicode U+000A newline symbol \n

%{tab}

Unicode U+0009 tab symbol \t

27.7. list-workspaces

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

Print workspaces that satisfy conditions

OPTIONS

-h, --help

Print help

--format <output-format>

Specify output format. See "Output Format" section for more details

--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 the 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.

--format <output-format>

Specify output format. See "Output Format" section for more details

OUTPUT FORMAT

Output format can be configured with optional [--format <output-format>] option. <output-format> supports string interpolation.

If not specified, the default <output-format> is:
%{workspace}

The following variables can be used inside <output-format>:

%{workspace}

String. Name of the belonging workspace

%{monitor-id}

Number. Sequential number of the belonging monitor

%{monitor-name}

String. Name of the belonging monitor

%{right-padding}

A special variable which expands with a minimum number of spaces required to form a right padding in the appropriate column

%{newline}

Unicode U+000A newline symbol \n

%{tab}

Unicode U+0009 tab symbol \t