> ## Documentation Index
> Fetch the complete documentation index at: https://flightdeck.saad.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Config reference

> Complete reference for FlightDeck TOML configuration.

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](/guide#custom-config-location)).

See the [Guide](/guide) for a narrative introduction, and [default-config.toml](config-examples/default-config.toml) for a ready-to-copy starter.

A *dynamic* value can be either a scalar or a per-monitor array:

```toml theme={null}
# 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`).

```toml theme={null}
config-version = 2
```

## after-startup-command

**Type:** String or array of FlightDeck commands · **Default:** `[]`

Commands to run after FlightDeck starts.

```toml theme={null}
after-startup-command = ['exec-and-forget borders active_color=0xffe1e3e4']
```

## after-login-command

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

## start-at-login

**Type:** Boolean · **Default:** `false`

Register FlightDeck as a login item so it starts automatically when you log in to macOS.

```toml theme={null}
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.

```toml theme={null}
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.

```toml theme={null}
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.

```toml theme={null}
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.

```toml theme={null}
focus-next-window-on-window-closed = false
```

<Note>
  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.
</Note>

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

```toml theme={null}
accordion-padding = 30
```

## default-root-container-layout

**Type:** String · **Default:** `tiles` · **Values:** `tiles`, `accordion`

Default layout for the root container of every workspace.

```toml theme={null}
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.

```toml theme={null}
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](/guide#normalization) section of the Guide.

```toml theme={null}
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](/guide#normalization) section of the Guide.

```toml theme={null}
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.

```toml theme={null}
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](/guide#on-focus-changed-callbacks) in the Guide.

```toml theme={null}
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.

```toml theme={null}
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](/guide#binding-modes) in the Guide.

```toml theme={null}
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.

```toml theme={null}
[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](/guide#keyboard-layouts-and-key-mapping) in the Guide.

```toml theme={null}
[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.

```toml theme={null}
[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](/guide#assign-workspaces-to-monitors) in the Guide.

```toml theme={null}
[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](/guide#binding-modes) in the Guide.

```toml theme={null}
[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](/guide#on-window-detected-callback) in the Guide.

```toml theme={null}
[[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](https://github.com/nikitabobko/AeroSpace/issues/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).