Config reference - FlightDeck Docs

This page documents every top-level key accepted by FlightDeck’s TOML configuration file. The config file is loaded from ~/.flightdeck.toml, ${XDG_CONFIG_HOME}/flightdeck/flightdeck.toml, ~/.aerospace.toml, or ${XDG_CONFIG_HOME}/aerospace/aerospace.toml (a flightdeck.toml takes precedence; see Custom config location). See the Guide for a narrative introduction, and default-config.toml for a ready-to-copy starter. A dynamic value can be either a scalar or a per-monitor array:

# Constant form
gaps.outer.top = 8

# Per-monitor form: last element is the default
gaps.outer.top = [{ monitor.main = 16 }, { monitor."some-pattern" = 32 }, 8]

config-version

Type: Integer · Default: 1 · Range: 1–2 Declares the config format version. Required to use options that are only available from a given version (e.g. persistent-workspaces requires config-version = 2).

config-version = 2

after-startup-command

Type: String or array of FlightDeck commands · Default: [] Commands to run after FlightDeck starts.

after-startup-command = ['exec-and-forget borders active_color=0xffe1e3e4']

Type: Array · Default: [] · Status: Deprecated since AeroSpace 0.19.0 Previously ran commands after macOS login. Removed in favour of after-startup-command. An empty array is accepted for backwards compatibility; any non-empty value is a parse error. Type: Boolean · Default: false Register FlightDeck as a login item so it starts automatically when you log in to macOS.

start-at-login = true

auto-reload-config

Type: Boolean · Default: false Reload the config automatically whenever the config file is saved. After enabling this option, reload once manually to activate auto-reload.

auto-reload-config = true

automatically-unhide-macos-hidden-apps

Type: Boolean · Default: false Automatically un-hide applications that were hidden with macOS ⌘H / ⌘⌥H. Useful if you never intentionally hide apps and want to avoid accidentally losing windows.

automatically-unhide-macos-hidden-apps = true

focus-follows-mouse

Type: Table · Default: disabled Focus the normal managed window under the pointer when the pointer enters it. Fullscreen windows and accessibility elements that do not represent normal windows are ignored.

focus-follows-mouse.enabled = true

Nested keys

Key	Type	Description
`enabled`	Boolean, default `false`	Enable focus follows mouse

focus-next-window-on-window-closed

Type: Boolean · Default: true Controls what happens to focus when the focused application’s final managed window is closed. When true (the default), FlightDeck lets focus move to the next window. This matches standard macOS behavior and avoids leaving a focused application that no longer has any windows. When false, FlightDeck keeps the now-windowless application focused instead of transferring focus elsewhere. This is useful if you want an immediate ⌘Q to quit the application whose last window you just closed.

focus-next-window-on-window-closed = false

Regardless of this setting, macOS may activate a same-application window that lives on another, non-visible workspace when you close the application’s visible window — leaving keyboard focus on a window you cannot see. This is a macOS behavior that the setting cannot override. Because of this, false is only useful when an application’s windows stay on a single workspace; if you keep windows of the same application spread across workspaces, leave this option at its default.

accordion-padding

Type: Integer in pixels · Default: 30 Width of the overlap padding shown in accordion layout. Set to 0 to disable the padding effect entirely.

accordion-padding = 30

default-root-container-layout

Type: String · Default: tiles · Values: tiles, accordion Default layout for the root container of every workspace.

default-root-container-layout = 'tiles'

default-root-container-orientation

Type: String · Default: auto · Values: horizontal, vertical, auto Default orientation for the root container of every workspace. auto uses horizontal for monitors wider than they are tall, and vertical otherwise.

default-root-container-orientation = 'auto'

enable-normalization-flatten-containers

Type: Boolean · Default: true Automatically flatten redundant nested containers that have the same orientation as their parent. See the Normalization section of the Guide.

enable-normalization-flatten-containers = true

NOTE: Enabling this option makes the split command have no effect. Use join-with instead.

enable-normalization-opposite-orientation-for-nested-containers

Type: Boolean · Default: true Automatically set the orientation of a new nested container to be the opposite of its parent. See the Normalization section of the Guide.

enable-normalization-opposite-orientation-for-nested-containers = true

persistent-workspaces

Type: Array of strings · Default: [] · Requires: config-version = 2 Workspace names that remain alive even when empty and invisible. Without this option, empty workspaces are destroyed and their names freed.

persistent-workspaces = ["1", "2", "3", "A", "B", "C"]

on-focus-changed

Type: String or array of FlightDeck commands · Default: [] Commands to run every time focus changes (window or monitor). See on-focus-changed callbacks in the Guide.

on-focus-changed = ['exec-and-forget borders active_color=0xffe1e3e4']

on-focused-monitor-changed

Type: String or array of FlightDeck commands · Default: [] Commands to run when the focused monitor changes. A common use is to warp the mouse cursor to the new monitor’s center.

on-focused-monitor-changed = ['move-mouse monitor-lazy-center']

on-mode-changed

Type: String or array of FlightDeck commands · Default: [] Commands to run every time the active binding mode changes. See Binding modes in the Guide.

on-mode-changed = ['exec-and-forget echo mode changed']

exec-on-workspace-change

Type: Array of shell command tokens · Default: [] · Status: Deprecated Shell command tokens to execute whenever the focused workspace changes. The environment exposes AEROSPACE_FOCUSED_WORKSPACE and AEROSPACE_PREV_WORKSPACE.

exec

Type: Table Controls the environment that exec-and-forget and exec-on-workspace-change commands run in.

[exec]
inherit-env-vars = true

[exec.env-vars]
PATH = '/opt/homebrew/bin:/usr/local/bin:${PATH}'

Nested keys

Key	Type	Description
`inherit-env-vars`	Boolean, default `true`	Inherit the current process environment when running exec commands
`env-vars`	Table of strings	Additional or overriding environment variables; values support `${VAR}` interpolation

key-mapping

Type: Table Configures the keyboard preset used to resolve key names in binding mode definitions. See Key mapping in the Guide.

[key-mapping]
preset = 'qwerty'

Nested keys

Key	Type	Description
`preset`	String: `qwerty`, `dvorak`, or `colemak`	Physical key layout preset; defaults to `qwerty`

gaps

Type: Table Spacing between windows and between windows and monitor edges. Each sub-key accepts a constant integer or a dynamic per-monitor array.

[gaps]
inner.horizontal = 10
inner.vertical   = 10
outer.left       = 8
outer.bottom     = 8
outer.top        = [{ monitor.main = 24 }, 8]
outer.right      = 8

Nested keys

Key	Type	Description
`inner.horizontal`	Dynamic integer, default `0`	Gap between windows arranged side-by-side
`inner.vertical`	Dynamic integer, default `0`	Gap between windows stacked vertically
`outer.left`	Dynamic integer, default `0`	Gap between the leftmost window column and the monitor edge
`outer.right`	Dynamic integer, default `0`	Gap between the rightmost window column and the monitor edge
`outer.top`	Dynamic integer, default `0`	Gap between the top window row and the monitor edge
`outer.bottom`	Dynamic integer, default `0`	Gap between the bottom window row and the monitor edge

workspace-to-monitor-force-assignment

Type: Table mapping workspace names to monitor patterns or arrays Pin named workspaces to specific monitors. See Assign workspaces to monitors in the Guide.

[workspace-to-monitor-force-assignment]
1 = 'main'
2 = ['secondary', 'main']

mode

Type: Table mapping mode names to binding tables Defines binding modes and their key bindings. The main mode must always be present. See Binding modes in the Guide.

[mode.main.binding]
alt-h = 'focus left'
alt-shift-semicolon = 'mode service'

[mode.service.binding]
esc = ['reload-config', 'mode main']

on-window-detected

Type: Array of tables Callbacks that run when a new window is detected. Each entry may use any command as its condition. See on-window-detected in the Guide.

[[on-window-detected]]
if = 'test %{app-bundle-id} = com.apple.finder'
run = 'move-node-to-workspace F'

[[on-window-detected]]
if = 'test %{app-name} ~= terminal'
run = ['layout floating', 'move-node-to-workspace T']
check-further-callbacks = true

Keys

Key	Type	Description
`if`	Command string	Optional condition. The callback matches when the command exits successfully
`check-further-callbacks`	Boolean, default `false`	Continue evaluating later callbacks after this one matches
`run`	String or array	Commands to execute when this callback matches

The legacy if.app-id, if.app-name-regex-substring, if.window-title-regex-substring, if.workspace, and if.during-aerospace-startup matcher keys remain supported for compatibility.

indent-for-nested-containers-with-the-same-orientation

Type: Ignored · Status: Deprecated Drop this key from your config. See AeroSpace#96.

non-empty-workspaces-root-containers-layout-on-startup

Type: String · Status: Deprecated Drop this key from your config. Only the value "smart" is accepted (for backwards-compatibility error reporting).

​config-version

​after-startup-command

​after-login-command

​start-at-login

​auto-reload-config

​automatically-unhide-macos-hidden-apps

​focus-follows-mouse

​Nested keys

​focus-next-window-on-window-closed

​accordion-padding

​default-root-container-layout

​default-root-container-orientation

​enable-normalization-flatten-containers

​enable-normalization-opposite-orientation-for-nested-containers

​persistent-workspaces

​on-focus-changed

​on-focused-monitor-changed

​on-mode-changed

​exec-on-workspace-change

​exec

​Nested keys

​key-mapping

​Nested keys

​gaps

​Nested keys

​workspace-to-monitor-force-assignment

​mode

​on-window-detected

​Keys

​indent-for-nested-containers-with-the-same-orientation

​non-empty-workspaces-root-containers-layout-on-startup

config-version

after-startup-command

after-login-command

start-at-login

auto-reload-config

automatically-unhide-macos-hidden-apps

focus-follows-mouse

Nested keys

focus-next-window-on-window-closed

accordion-padding

default-root-container-layout

default-root-container-orientation

enable-normalization-flatten-containers

enable-normalization-opposite-orientation-for-nested-containers

persistent-workspaces

on-focus-changed

on-focused-monitor-changed

on-mode-changed

exec-on-workspace-change

exec

Nested keys

key-mapping

Nested keys

gaps

Nested keys

workspace-to-monitor-force-assignment

mode

on-window-detected

Keys

indent-for-nested-containers-with-the-same-orientation

non-empty-workspaces-root-containers-layout-on-startup