### Startup script example with KiwiDesk.set_gap_global, KiwiDesk.exec, and KiwiDesk.on

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Commands at init.lua top level run on load and reload. This example sets base gaps before profiles load, fires an async command, and subscribes to the space_change event.

```lua
-- Set base gaps; these apply before a profile loads.
KiwiDesk.set_gap_global(10)


-- Fire an async command at startup:
KiwiDesk.exec("sketchybar --reload")


-- Subscribe to an event:
KiwiDesk.on("space_change", function(space_id)
    print("Switched to space: " .. space_id)
end)
```

--------------------------------

### stack.promote example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves the focused window to the master zone. Expects nothing.

```lua
stack.promote()
```

--------------------------------

### Install KiwiDesk via Homebrew

Source: https://kiwidesk.kiwicanopy.com/docs

Use this command to install the KiwiDesk application and add the kiwidesk CLI to your PATH.

```bash
brew install --cask kiwicanopy/tap/kiwidesk
```

--------------------------------

### KiwiDesk CLI usage examples

Source: https://kiwidesk.kiwicanopy.com/docs/cli

Shows the basic command forms for the kiwidesk binary: running the window manager, sending commands, and querying help or version. The Homebrew cask installs it as lower-case kiwidesk on PATH; a source build produces .build/release/KiwiDesk instead.

```bash
kiwidesk                      # run the window manager
kiwidesk <command> [args...]  # send a command to the app
kiwidesk help                 # local usage
kiwidesk --version            # local version (no app needed)
kiwidesk list_commands        # every command, grouped
kiwidesk help <name>          # one command's arguments
```

--------------------------------

### Event hooks example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Example of using event hooks that coexist with the GUI-managed settings.

```lua
-- Event hooks, control flow, helpers, print, locals — all fine.
for _, event in ipairs({ "space_change", "focus_change" }) do
  KiwiDesk.on(event, function()
    KiwiDesk.exec("sketchybar --trigger kiwidesk_update")
  end)
end
```

--------------------------------

### stack.demote example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves the focused window out of the master zone into the stack. Expects nothing.

```lua
stack.demote()
```

--------------------------------

### Example Profile JSON Configuration

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

A sample profile JSON file demonstrating monitor sets, layout strategies, window settings, and custom keybindings.

```json
{
  "name": "Desk One",
  "default": true,            // this count's fallback profile
  "monitor_sets": [
    {
      "monitors": ["Built-in Retina Display:1728x1117"],
      "space_monitor_map": {  // explicit pins only (sparse)
        "2": "Built-in Retina Display:1728x1117"
      }
    }
  ],
  "main_spaces": ["1"],       // follow the main display
  "fallback_space": "1",      // rehome target on switch
  "saved_at": "2026-07-04T12:00:00Z",
  "settings": {
    "drag": {
      "corner_radius": 16,
      "ghost": {
        "enabled": true, "border": true,
        "border_color": "#347957", "border_width": 5,
        "border_alignment": "inside",
        "fill": true, "fill_color": "#34795740"
      },
      "drop_zone": {
        "enabled": true, "border": true,
        "border_color": "#C2790A", "border_width": 5,
        "border_alignment": "inside",
        "fill": true, "fill_color": "#C2790A40"
      }
    },
    "gap": {
      "global": {
        "inner": { "horizontal": 20, "vertical": 20 },
        "outer": {
          "top": 20, "bottom": 20, "left": 20, "right": 20
        }
      },
      "override": {}              // per space id
    },
    "layout": {
      "bsp": {
        "new_window_placement": "after_focused",
        "ratio_h": 0.5,
        "ratio_v": 0.5,
        "strategy": "alternating"
      },
      "grid": { "columns": 3, "rows": 2, "type": "dynamic",
                "fill_empty_cells": true,
                "split_direction": "horizontal",
                "new_window_placement": "last" },
      "monocle": { "orientation": "horizontal",
                   "app_bar": { "enabled": true,
                                "edge": "top",
                                "background_style": "boxed",
                                "item_size": 0 } },
      "scroll": { "anchor": "follow", "slot_size": 0,
                  "new_window_placement": "after_focused" },
      "stack": { "master_count": 1, "master_ratio": 0.6,
                 "overflow_style": "cascade_overflow",
                 "new_window_placement": "first" }
    },
    "min_window_size": 300,
    "new_window_placement_override": {},  // per space id
    "space": { "icon": { "2": "envelope" } }  // per space id
  },
  "space_modes": { "1": "stack", "2": "bsp" },
  // Optional sparse keybinding override (see Config
  // cascade): only the layers/rows this profile changes.
  // Omit the key entirely to inherit the base shortcuts.
  "layers": [
    {
      "name": "default",
      "bindings": [
        { "combo": "alt+h", "lua": "KiwiDesk.focus(\"left\")",
          "kind": "custom", "label": "" }
      ]
    }
  ]
}
```

--------------------------------

### Command Listing Output Format

Source: https://kiwidesk.kiwicanopy.com/docs/cli

Example of the command listing format, showing command groups and their respective arguments.

```text
scroll
  set_anchor <anchor>                Sets where the focused …
  set_orientation <orientation>      Sets whether columns scroll …
  set_slot_size_override <space> <size>   Overrides the slot …
```

--------------------------------

### Example window lifecycle event payloads

Source: https://kiwidesk.kiwicanopy.com/docs/cli

Sample JSON event payloads for window creation and destruction events.

```json
{"event": "window_created",
 "data": {"window_id": 4711, "app": "Ghostty",
          "space_id": "2", "reason": "new",
          "bundle_id": "com.mitchellh.ghostty"}}
{"event": "window_destroyed",
 "data": {"window_id": 4711, "app": "Ghostty",
          "space_id": "2", "reason": "closed",
          "bundle_id": "com.mitchellh.ghostty",
          "desktop": null}}
```

--------------------------------

### grid.set_fill_empty_cells example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

If true, resizes windows to fill empty cells. Expects true or false.

```lua
grid.set_fill_empty_cells(true)

```

--------------------------------

### KiwiDesk.exec

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Starts a shell command in the background and returns immediately. Accepts a command string, optional callback, timeout, and dedup flag. Returns the child's pid or nil if the command could not be started or was skipped as a duplicate.

```APIDOC
## KiwiDesk.exec

### Description
Starts a shell command in the background and returns immediately. The command is run via /bin/sh -c, so pipes, quoting, &&, and $PATH lookups work as in a terminal. Returns the child's pid (a number), or nil when the command could not be started or was skipped as a duplicate.

### Method
N/A (Lua function)

### Parameters
- **command** (string) - Required - The command string to run via /bin/sh -c.
- **callback** (function) - Optional - Called once the command has exited, with arguments: code (number, exit code), stdout (string, everything written to stdout), stderr (string, everything written to stderr).
- **timeout** (number) - Optional - Number of seconds before the command receives SIGTERM. Defaults to 30 s. Pass 0 or negative for no limit.
- **dedup** (boolean) - Optional - Default true. If an identical command is already running, a second exec is skipped (returns nil) and its callback is not invoked. Pass false to allow parallel identical commands.

### Return Value
- **pid** (number) - The child's process ID, or nil if the command could not be started or was skipped as a duplicate.

### Notes
- stdout and stderr are each capped at ~1 MB; output beyond the cap is truncated and ends with '[output truncated at 1 MB]'.
- Exec children are fire-and-forget; when KiwiDesk exits, running children are re-parented to launchd and finish naturally.
- When the number of outstanding children crosses 20, KiwiDesk logs a warning. The live count is available via get_state().exec_running.
- The child's PATH gets /opt/homebrew/bin and /usr/local/bin appended.

### Example
```lua
-- Fire and forget:
KiwiDesk.exec("sketchybar --reload")

-- Read a command's output via the callback:
KiwiDesk.exec("defaults read -g AppleInterfaceStyle",
    function(code, out, err)
        dark = (code == 0 and out:match("Dark") ~= nil)
    end)

-- With a 5-second timeout:
KiwiDesk.exec("some-slow-tool", function(code, out, err)
    -- code is non-zero if killed by the watchdog
end, 5)

-- No limit (deliberately long-running), and opt out of dedup so
-- two identical copies can run at once:
KiwiDesk.exec("long-running-tool", nil, 0, false)
```
```

--------------------------------

### os.execute usage examples

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Shows the fire-and-forget nature of os.execute and warns against assuming synchronous completion for file system operations.

```lua
-- Fine: fire-and-forget side effect.
os.execute("open -a Spotify")


-- Wrong: the file is NOT guaranteed to exist yet here.
os.execute("touch /tmp/marker")
-- do_something("/tmp/marker")
```

--------------------------------

### Install borders via Homebrew

Source: https://kiwidesk.kiwicanopy.com/docs/recipes/jankyborders

Install the borders tool, which JankyBorders relies on, using Homebrew on macOS. Run this command in your terminal to set up the borders utility.

```bash
brew install felixkratz/formulae
```

--------------------------------

### KiwiDesk.exec usage examples

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Demonstrates fire-and-forget execution, reading command output via callbacks, setting custom timeouts, and disabling deduplication for long-running processes.

```lua
-- Fire and forget:
KiwiDesk.exec("sketchybar --reload")


-- Read a command's output via the callback:
KiwiDesk.exec("defaults read -g AppleInterfaceStyle",
    function(code, out, err)
        dark = (code == 0 and out:match("Dark") ~= nil)
    end)


-- With a 5-second timeout:
KiwiDesk.exec("some-slow-tool", function(code, out, err)
    -- code is non-zero if killed by the watchdog
end, 5)


-- No limit (deliberately long-running), and opt out of dedup so
-- two identical copies can run at once:
KiwiDesk.exec("long-running-tool", nil, 0, false)
```

--------------------------------

### Move window to Desktop

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Examples of moving the focused window to a specific Desktop, with and without an optional Space identifier.

```lua
KiwiDesk.move_to_desktop(3)
KiwiDesk.move_to_desktop(3, "mail")
```

--------------------------------

### gui.json rule families example

Source: https://kiwidesk.kiwicanopy.com/docs/user-guide

Example of the gui.json configuration file showing the three rule families: app_rules, float_rules, and ignore_rules. An absent entry inherits, and a tombstone whose base rule no longer exists is harmless and becomes effective again if that base rule returns. The three families resolve independently; effective Ignore is applied last as the hard gate.

```json
{
  "app_rules": { "com.apple.mail": null },
  "float_rules": {
    "com.apple.calculator": null,
    "com.apple.finder:Get Info": true
  },
  "ignore_rules": {
    "eu.exelban.Stats": true,
    "com.example.inherited": null
  }
}
```

--------------------------------

### move_space_to_display example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves a whole space to a monitor immediately and shows it there. The display reference can be a 1-based number (1 is main) or a monitor fingerprint/name. This is a runtime move; use pin_space_to_display to make it persist across dock/undock. Creates the space if it does not exist.

```lua
KiwiDesk.move_space_to_display("mail", 2)      -- second monitor
KiwiDesk.move_space_to_display(3, "DELL U2723QE:3840x2160")

```

--------------------------------

### app_bar.set_thickness example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the bar's thickness, carved out of the layout. Expects a positive number in points.

```lua
app_bar.set_thickness(32)
```

--------------------------------

### Handle Unknown Commands

Source: https://kiwidesk.kiwicanopy.com/docs/cli

Example of the error output when an invalid command name is provided.

```bash
$ kiwidesk help focsu
error: unknown command: focsu (did you mean focus?)
```

--------------------------------

### Subscribe to space_change event

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Example of registering a callback for the space_change event to trigger a sketchybar update.

```lua
KiwiDesk.on("space_change", function(space_id, mode)
    KiwiDesk.exec(
        "sketchybar --trigger space_change SPACE="
        .. space_id)
end)
```

--------------------------------

### gui.json top-level structure

Source: https://kiwidesk.kiwicanopy.com/docs/user-guide

Shows the top-level structure of the gui.json file with example values for spaces, app_rules, float_rules, ignore_rules, profile_bindings, and layers.

```json
{
  "spaces": [ "1", "2", "mail" ],
  "app_rules": { "com.spotify.client": "music" },
  "float_rules": [ "com.apple.calculator" ],
  "ignore_rules": [ "eu.exelban.Stats" ],
  "profile_bindings": {
    "9C1F2A44-3B0E-4E7D-9A21-6D5C8B7E0143": {
      "profile": "Developer", "desktop": 1
    }
  },
  "layers": [
    { "name": "default", "bindings": [...] }
  ]
}
```

--------------------------------

### Help text JSON format

Source: https://kiwidesk.kiwicanopy.com/docs/translating

Example of a .help key value containing Markdown bold markers and literal line breaks.

```json
"layout_params.overflow.stack.help":
  "**Cascade overflow** — Keeps as many windows fully tiled
   as fit…\n**Cascade all** — Cascades the whole stack…"
```

--------------------------------

### quit.set_layout example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the quit layout strategy to 'grid', the only strategy currently available. This builds a per-display grid and round-robin fills it, with cascading piles and a raise circle. Profile JSON key: quit.layout. Default: grid.

```lua
quit.set_layout("grid")
```

--------------------------------

### grid.set_dimensions example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

For rigid grids, locks the layout to this size. Expects two positive integers (columns, rows).

```lua
grid.set_dimensions(3, 2)

```

--------------------------------

### Example focus_change event payload

Source: https://kiwidesk.kiwicanopy.com/docs/cli

A sample JSON event payload for a focus change event, including window metadata.

```json
{"event": "focus_change",
 "data": {"window_id": 4711, "app": "Ghostty",
          "bundle_id": "com.mitchellh.ghostty",
          "title": "~/src — zsh"}}
```

--------------------------------

### KiwiDesk service control commands

Source: https://kiwidesk.kiwicanopy.com/docs/cli

Use these commands to manage the background agent. 'start' bootstraps the agent, 'stop' unloads it, 'restart' reloads the job, and 'status' provides information on the loaded state and PID.

```bash
kiwidesk service start     # LaunchAgent: run at login,
                           # restart after crashes
kiwidesk service stop
kiwidesk service restart
kiwidesk service status    # loaded? running? pid?
```

--------------------------------

### bsp.set_ratio_h example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the first window's share of every side-by-side BSP split. Expects a number between 0 and 1 (default 0.5). resize("x", ...) nudges this value; stacked splits keep their own ratio.

```lua
bsp.set_ratio_h(0.5)
```

--------------------------------

### app_bar.set_font_size example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the font size in points. 0 means auto (default), scaling with bar thickness; any positive value pins the font size.

```lua
app_bar.set_font_size(0)
```

--------------------------------

### Define float_rules in Lua

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Example of a float_rules table configuration. This matches all windows of the Calculator app and specifically the 'Get Info' window of the Finder app.

```lua
float_rules = {
    "com.apple.calculator",
    "com.apple.finder:Get Info",
}
```

--------------------------------

### stack.set_master_ratio example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the master zone's share of the split axis. Expects a number between 0 and 1. At layout time the effective ratio is clamped so both zones keep min_window_size; the stored value stays untouched and is honored again on a wider display.

```lua
stack.set_master_ratio(0.6)
```

--------------------------------

### animations.set_size_policy example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the size policy to "mid_slide" for legacy sizing. Expects "smooth" (default) or "mid_slide". Engine-only and not persisted to a profile. Set from init.lua to make override stick.

```lua
-- fall back to the legacy sizing for a stubborn app
animations.set_size_policy("mid_slide")
```

--------------------------------

### bsp.set_ratio_v example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the first window's share of every stacked (top/bottom) BSP split. Expects a number between 0 and 1 (default 0.5). resize("y", ...) nudges this value independently of the side-by-side ratio.

```lua
bsp.set_ratio_v(0.5)
```

--------------------------------

### app_bar.set_alignment example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Places the item group along the bar while it fits. Expects 'start', 'center', or 'end' (default 'center'). Values are edge-relative; once items overflow and scroll, all three values behave the same.

```lua
app_bar.set_alignment("start")
```

--------------------------------

### stack.set_stack_position example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets which side of the space the stack zone takes. Expects "top", "right" (default), "bottom", or "left". The master zone gets the rest; left/right split the width, top/bottom the height. The stack zone's lineup derives from the position.

```lua
stack.set_stack_position("bottom")
```

--------------------------------

### KiwiDesk.spawn_new(bundleIdentifier)

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Always launches a new instance of the app, even if one is already running. Matching is keyed on the bundle id.

```APIDOC
## KiwiDesk.spawn_new(bundleIdentifier)

### Description
Always launches a new instance of the app, even if one is already running. Matching is keyed on the bundle id.

### Method
Function call

### Parameters
- **bundleIdentifier** (string) - Required - The app bundle identifier (e.g., com.apple.Terminal).

### Example
```lua
KiwiDesk.bind("ctrl+alt+return", function()
    KiwiDesk.spawn_new("com.apple.Terminal")
end)
```
```

--------------------------------

### app_bar.set_background_style example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets where the background is drawn. Expects 'boxed' or 'plain' (default 'plain'). 'boxed' draws a box per item honoring corner roundness; 'plain' draws a shared translucent strip. Liquid Glass is now a separate finish toggle, set_liquid_glass.

```lua
app_bar.set_background_style("plain")
```

--------------------------------

### Build KiwiDesk from source

Source: https://kiwidesk.kiwicanopy.com/docs

Use this command to build the KiwiDesk binary from source. The resulting executable is located at .build/release/KiwiDesk.

```bash
swift build -c release
```

--------------------------------

### pin_space_to_display example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Pins a space to a monitor by fingerprint so the assignment survives dock/undock and, when declared in init.lua, a relaunch. Overrides any Main-role assignment. Creates the space if new. Under a GUI-managed config, a Lua-set pin is a session override; under a Lua-managed config it persists because init.lua re-runs.

```lua
KiwiDesk.pin_space_to_display("mail", 2)

```

--------------------------------

### animations.set_on_space_change example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Enables or disables coordinated animation when switching spaces. Expects true or false (default false). Off is faster; slow apps can stutter when on. macOS Desktop switches are never animated.

```lua
animations.set_on_space_change(false)
```

--------------------------------

### Set Space Bar alignment

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Places Space items and the front-app segment along the bar. Accepts "start", "center", or "end", default "center". Values are edge-relative; for a left bar, start is its top.

```lua
space_bar.set_alignment("center")
```

--------------------------------

### KiwiDesk.move_to_space_and_follow(space)

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves the focused window to the specified space and switches you there with it.

```APIDOC
## KiwiDesk.move_to_space_and_follow(space)

### Description
Moves the focused window to the specified space and switches you there with it.

### Method
Function call

### Endpoint
KiwiDesk.move_to_space_and_follow(space)

### Parameters
- **space** (number or string) - Required - A space identifier.

### Request Example
```lua
KiwiDesk.move_to_space_and_follow("mail")
KiwiDesk.move_to_space_and_follow(3)
```

### Response
No return value documented.
```

--------------------------------

### app_bar.set_highlight_color example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the highlight color of the active indicator (outline or edge mark).

```lua
app_bar.set_highlight_color("#8DB354")
```

--------------------------------

### Bind spawn_new to ctrl+alt+return

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Binds the spawn_new function to the ctrl+alt+return shortcut. Always launches a new instance of the app, even if one is already running. Matching is keyed on the bundle id, exactly like pull_or_spawn.

```lua
KiwiDesk.bind("ctrl+alt+return", function()
    KiwiDesk.spawn_new("com.apple.Terminal")
end)
```

--------------------------------

### stack.set_master_count example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets how many windows are in the master zone. Expects a positive integer.

```lua
stack.set_master_count(1)
```

--------------------------------

### get_state: Retrieve current window and space state

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Returns a table with fields for active space, spaces, windows, away windows, monitor count, desktop, and exec_running. Each window object includes id, app, title, and floating. The example prints the active space, desktop, and lists floating windows.

```lua
local state = KiwiDesk.get_state()
print(state.active_space)
print(state.desktop)


for _, window in ipairs(state.windows) do
    if window.floating then
        print("Floating: " .. window.app)
    end
end
```

--------------------------------

### KiwiDesk.open_settings()

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Opens the Settings window and brings it to the front. If Settings is already open, it returns to the Home tab rather than closing, preserving unsaved draft edits.

```APIDOC
## KiwiDesk.open_settings()

### Description
Opens the Settings window and brings it to the front. If the window is already open, it returns to the Home tab instead of closing, preserving unsaved draft edits.

### Method
N/A (Lua function)

### Endpoint
N/A (Lua function)

### Parameters
None.

### Request Example
```lua
KiwiDesk.bind("ctrl+alt+comma", function()
    KiwiDesk.open_settings()
end)
```

### Response
No return value.
```

--------------------------------

### Move window to a space and follow

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves the focused window to the target space and switches the current view to that space.

```lua
KiwiDesk.move_to_space_and_follow("mail")
KiwiDesk.move_to_space_and_follow(3)
```

--------------------------------

### KiwiDesk.pull_or_spawn(bundleIdentifier)

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Focuses the app's window if already running, otherwise launches a new instance. Cycling through windows is supported by repeated presses.

```APIDOC
## KiwiDesk.pull_or_spawn(bundleIdentifier)

### Description
If the app is already running, focuses its window. If not running, launches a new instance. Repeated presses cycle through the app's windows in space order and slot order.

### Method
Function call

### Parameters
- **bundleIdentifier** (string) - Required - The app bundle identifier (e.g., com.apple.safari).

### Example
```lua
KiwiDesk.bind("ctrl+return", function()
    KiwiDesk.pull_or_spawn("com.apple.safari")
end)
```
```

--------------------------------

### Example space_change event payload

Source: https://kiwidesk.kiwicanopy.com/docs/cli

A sample JSON event payload for a space change event.

```json
{"event": "space_change",
 "data": {"space_id": "3", "layout_mode": "bsp",
          "window_count": 4}}
```

--------------------------------

### KiwiDesk.toggle_sticky

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Flips the focused window between global sticky and off. This example demonstrates binding the toggle to a keyboard shortcut.

```lua
KiwiDesk.bind("cmd+alt+s", function()
    KiwiDesk.toggle_sticky()
end)
```

--------------------------------

### stack.promote

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves the focused window to the master zone.

```APIDOC
## stack.promote

### Description
Moves the focused window to the master zone.

### Parameters
None.

### Example
```

stack.promote()

```
```

--------------------------------

### Event subscription and cold-start watchdog

Source: https://kiwidesk.kiwicanopy.com/docs/recipes/sketchybar

Subscribes to the 'kiwidesk_update' event to refresh spaces, performs an initial update, and sets up a watchdog that polls every 2 seconds until the first successful read, then disables itself.

```lua
-- =============================================================
-- EVENT SUBSCRIPTION & COLD-START WATCHDOG
-- =============================================================
SBAR.add("event", "kiwidesk_update")


local event_item = SBAR.add("item", { drawing = false })
event_item:subscribe("kiwidesk_update", function()
    update_spaces()
end)


-- Initial update
update_spaces()


-- Self-heal: on a cold start (sketchybar loads before the
-- KiwiDesk socket is ready, e.g., a reload KiwiDesk triggers
-- while loading init.lua), the initial update fails silently.
-- Poll every 2 seconds until the first successful read, then
-- stop and go event-driven.
local watchdog = SBAR.add("item", {
    drawing = false,
    update_freq = 2
})
watchdog:subscribe("routine", function()
    if has_data then
        watchdog:set({ update_freq = 0 })
    else
        update_spaces()
    end
end)
```

--------------------------------

### monocle.set_orientation_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global orientation for one space. Expects a space identifier and an orientation string.

```lua
monocle.set_orientation_override("3", "vertical")

```

--------------------------------

### stack.set_new_window_placement example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets where new windows enter the stack's order. Expects "first", "last", "before_focused", or "after_focused". For stack, the default is "first" (dwm-style: new window becomes master).

```lua
stack.set_new_window_placement("last")
```

--------------------------------

### grid.set_auto_size_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global auto-size flag for one space. Expects a space identifier and a boolean.

```lua
grid.set_auto_size_override("3", true)

```

--------------------------------

### grid.set_fill_empty_cells_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global fill behavior for one space. Expects a space identifier and a boolean.

```lua
grid.set_fill_empty_cells_override("3", false)

```

--------------------------------

### move_to_desktop_and_follow example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves the focused window to a macOS Desktop and switches focus to that Desktop. The optional space identifier works like in move_to_desktop. Focus ends on the window, not just the screen. If the target Desktop is hidden, focus is handed over when the window reappears; if shown, focus stays. The returned 'switched' field describes only the switch, not the move.

```lua
KiwiDesk.move_to_desktop_and_follow(3)
KiwiDesk.move_to_desktop_and_follow(3, "mail")

```

--------------------------------

### scroll.set_orientation_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global orientation for one space. Expects a space identifier and an orientation string.

```lua
scroll.set_orientation_override("3", "vertical")

```

--------------------------------

### scroll.set_anchor_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global anchor for one space. Expects a space identifier and an anchor string.

```lua
scroll.set_anchor_override("3", "center")

```

--------------------------------

### app_bar.set_hover_fill_color example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the hover feedback color on clickable items. Default is #AACB5D80 (light translucent green).

```lua
app_bar.set_hover_fill_color("#AACB5D80")
```

--------------------------------

### Configure app_rules

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Maps application bundle identifiers to specific space identifiers to control where new windows are opened.

```lua
app_rules = {
    ["com.spotify.client"] = "music",
    ["com.apple.mail"]     = "mail",
}
```

--------------------------------

### app_bar.set_active_item_color example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the text and glyph color of the active (focused) item. Default is #8DB354 (kiwi green).

```lua
app_bar.set_active_item_color("#8DB354")
```

--------------------------------

### create_space example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Creates a space with an optional layout mode ("bsp", "stack", "scrolling", "grid", "monocle", "track", "floating"). Mainly for declaring a space and its mode up front in init.lua. If the space already exists, it is a no-op beyond setting the mode.

```lua
KiwiDesk.create_space("scratch", "monocle")

```

--------------------------------

### grid.set_split_direction_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global split direction for one space. Expects a space identifier and a direction string.

```lua
grid.set_split_direction_override("3", "vertical")

```

--------------------------------

### Manage Profiles with save_profile, load_profile, delete_profile, and set_default_profile

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Use these methods to persist, switch, remove, or set the default fallback for tiling profiles. Profiles act as the source of truth for layout settings like gaps, modes, and window positions.

```lua

KiwiDesk.save_profile("Developer Rig")
KiwiDesk.load_profile("Developer Rig")
KiwiDesk.delete_profile("Developer Rig")
KiwiDesk.set_default_profile("Developer Rig")

```

--------------------------------

### grid.set_type_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global grid type for one space. Expects a space identifier and a type string.

```lua
grid.set_type_override("3", "rigid")

```

--------------------------------

### grid.set_type example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the grid layout type. Expects "dynamic" or "rigid".

```lua
grid.set_type("dynamic")

```

--------------------------------

### stack.set_master_ratio_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global master ratio for a specific space. Expects a space identifier and a ratio number.

```lua
stack.set_master_ratio_override("3", 0.7)
```

--------------------------------

### Configuration file path

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

The default location for the KiwiDesk configuration file.

```text
~/.config/KiwiDesk/init.lua
```

--------------------------------

### stack.set_master_count_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global master count for a specific space. Expects a space identifier and a count number.

```lua
stack.set_master_count_override("3", 2)
```

--------------------------------

### Bind Profiles to Desktops with bind_profile_to_desktop

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Automatically loads a specific profile when a designated Mission Control desktop becomes active on the main display. Note that KiwiDesk resolves the provided desktop number to the specific desktop it currently identifies.

```lua

KiwiDesk.bind_profile_to_desktop(1, "Developer Rig")
KiwiDesk.bind_profile_to_desktop(2, "Creator Studio")

```

--------------------------------

### View Command Help Signature

Source: https://kiwidesk.kiwicanopy.com/docs/cli

Displays the full signature, arguments, and enum choices for a specific command.

```bash
$ kiwidesk help scroll.set_anchor
scroll.set_anchor <anchor>


  Sets where the focused window comes to rest in the viewport.


arguments:
  anchor        choice
                  center | start | end | follow
                  (ScrollingParams.Anchor)


  lua: scroll.set_anchor(anchor)
  cli: kiwidesk scroll.set_anchor <anchor>
```

--------------------------------

### KiwiDesk.focus_desktop(desktopNumber)

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Switches to the specified macOS Desktop. Returns a table with a 'switched' boolean indicating if the screen moved, and a 'note' if it was already on that Desktop. The command succeeds in both cases.

```APIDOC
## KiwiDesk.focus_desktop(desktopNumber)

### Description
Switches to the specified macOS Desktop, exactly as a swipe would. The screen that Desktop belongs to switches, and the bound profile, the remembered Space, and the `desktop_change` event all follow as they do for a swipe.

### Method
Command

### Parameters
#### Arguments
- **desktopNumber** (number) - Required - The macOS Desktop number, as shown in Mission Control. This is the same number used by `bind_profile_to_desktop`.

### Returns
A table with:
- **switched** (boolean) - `true` when the screen moved to the Desktop, `false` when that Desktop was already the one it showed.
- **note** (string) - Present when `switched` is `false`, explaining that the Desktop was already shown.

The command SUCCEEDS in both cases. Read the `switched` field to distinguish between the two outcomes.

### Example
```lua
KiwiDesk.focus_desktop(2)
```

### Notes
- Requires macOS's window-management bridge, which KiwiDesk looks up at runtime. Present on macOS 26.6.1 (observed 2026-08-18); no earlier build has been checked.
- The command rides stock settings with SIP on. KiwiDesk never asks you to disable SIP.
- Where the bridge is absent, the command does nothing and logs why. When run from the CLI, it prints the error instead.
```

--------------------------------

### Bind pull_or_spawn to ctrl+return

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Binds the pull_or_spawn function to the ctrl+return shortcut. It focuses the app if already running, otherwise launches a new instance. Pressing again cycles through the app's windows in space order, then slot order.

```lua
KiwiDesk.bind("ctrl+return", function()
    KiwiDesk.pull_or_spawn("com.apple.safari")
end)
```

--------------------------------

### KiwiDesk.make_sticky()

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Marks the focused window as globally sticky, making it visible on every space of every monitor. The window retains its existing floating or tiled state.

```APIDOC
## KiwiDesk.make_sticky()

### Description
Marks the focused window as globally sticky, making it visible on every space of every monitor. The window retains its existing floating or tiled state.

### Method
Function call

### Parameters
None

### Request Example
```lua
KiwiDesk.make_sticky()
```

### Response
No return value.
```

--------------------------------

### app_bar.set_group_adjacent_windows example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

If true, collapses adjacent same-app windows into one item with a count badge. Accepts true or false.

```lua
app_bar.set_group_adjacent_windows(true)
```

--------------------------------

### grid.set_dimensions_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global dimensions for one space. Expects a space identifier and two integers (columns, rows).

```lua
grid.set_dimensions_override("3", 4, 3)

```

--------------------------------

### help

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Returns the API surface as a table. With no argument, returns all commands grouped by Lua table. With one command name, returns that command's record.

```APIDOC
## help

### Description
Returns the API surface as a table. With no argument, returns every command grouped by its Lua table, each carrying its arguments and a one-line summary. With one command name, returns just that command's record.

### Method
N/A (Lua function)

### Endpoint
KiwiDesk.help

### Parameters
#### Arguments
- **command_name** (string) - Optional - The name of a command to get details for.

### Request Example
```lua
KiwiDesk.help()                     -- the whole surface
KiwiDesk.help("scroll.set_anchor")  -- one command
```

### Response
With no argument, returns a table with:
- **commands** (number) - How many commands there are.
- **groups** (array) - Array of groups, each with name and commands.

With one command name, returns a record with:
- **name** (string) - Command name.
- **qualified_name** (string) - Qualified name.
- **group** (string) - Group name.
- **command** (string) - Command string.
- **channel** (string) - Channel.
- **summary** (string) - One-line summary.
- **aliases** (array) - Aliases.
- **arguments** (array) - List of arguments. Enum-valued arguments also have values and value_type.

An unknown name is an error carrying a did-you-mean suggestion.
```

--------------------------------

### stack.set_overflow_style_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global overflow style for a specific space. Expects a space identifier and an overflow style string.

```lua
stack.set_overflow_style_override("3", "cascade_all")
```

--------------------------------

### bsp.set_ratio_v_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global stacked BSP ratio for one space. Expects a space identifier and a ratio number.

```lua
bsp.set_ratio_v_override("3", 0.4)
```

--------------------------------

### bsp.set_ratio_h_override example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Overrides the global side-by-side BSP ratio for one space. Expects a space identifier and a ratio number.

```lua
bsp.set_ratio_h_override("3", 0.6)
```

--------------------------------

### KiwiDesk.focus_space(space)

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Switches to the specified space, hiding the current space's tiled windows and revealing the target's. Keyboard focus follows to the target's focused window, or to Finder if the space is empty.

```APIDOC
## KiwiDesk.focus_space(space)

### Description
Switches to the specified space, hiding the current space's tiled windows and revealing the target's. Keyboard focus follows to the target's focused window, or to Finder if the space is empty.

### Method
Function call

### Endpoint
KiwiDesk.focus_space(space)

### Parameters
- **space** (number or string) - Required - A space identifier (number or string).

### Request Example
```lua
KiwiDesk.focus_space(2)
KiwiDesk.focus_space("mail")
```

### Response
No return value documented.
```