AeroSpace is an i3-like tiling window manager for macOS
Project homepage: https://github.com/nikitabobko/AeroSpace
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
andtiling
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
andaccordion
layouts (order of args doesn’t matter):
aerospace layout tiles accordion
-
Switch to
tiles
layout. Toggle the layout orientation if already intiles
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
-
Given this layout
h_tiles ├── window 1 (focused) └── window 2
move right
will result in the following layouth_tiles ├── window 2 └── window 1 (focused)
-
Given this layout
h_tiles ├── window 1 ├── window 2 (focused) └── v_tiles ├── window 3 └── window 4
move right
will result in the following layouth_tiles ├── window 1 └── v_tiles ├── window 3 ├── window 2 (focused) └── window 4
-
Given this layout
h_tiles ├── window 1 └── v_tiles ├── window 3 ├── window 2 (focused) └── window 4
move left
will result in the following layouth_tiles ├── window 1 ├── window 2 (focused) └── v_tiles ├── window 3 └── window 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 layoutv_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
-
Creates a new tiling container
-
Replaces the focused window with the container
-
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:
-
Run the command to start the debug session recording
-
Focus problematic window
-
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:
-
Workspace name
-
visible
is a special workspace name that represents the currently visible workspaces -
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-based index of a monitor as if monitors were ordered horizontally from left to right
-
all
is a special monitor ID that represents all monitors -
mouse
is a special monitor ID that represents monitor with the mouse -
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-based index of a monitor as if monitors were ordered horizontally from left to right
-
all
is a special monitor ID that represents all monitors -
mouse
is a special monitor ID that represents monitor with the mouse -
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