### Example: Hotkey Configuration for ActivateWindow

Source: https://wezterm.org/config/lua/keyassignment/ActivateWindow.html

An example demonstrating how to set up hotkeys to activate specific windows using the `ActivateWindow` function.

```APIDOC
## Example: Hotkey Configuration for ActivateWindow

### Description
This example shows how to configure hotkeys (CMD+ALT + number) to activate specific windows using the `ActivateWindow` function.

### Method
Configuration within WezTerm (Lua).

### Endpoint
N/A (Local configuration)

### Parameters
None directly for this snippet, but it uses `ActivateWindow`.

### Request Example
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {}
for i = 1, 8 do
  -- CMD+ALT + number to activate that window
  table.insert(config.keys, {
    key = tostring(i),
    mods = 'CMD|ALT',
    action = act.ActivateWindow(i - 1),
  })
end

return config
```

### Response
#### Success Response (200)
None (This is a configuration snippet).

#### Response Example
None
```

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

### Example: Creating New Workspace

Source: https://wezterm.org/config/lua/keyassignment/PromptInputLine.html

An example demonstrating how to use PromptInputLine to get a name for a new workspace and then create it.

```APIDOC
## Example: Creating New Workspace

### Description
This example demonstrates using `PromptInputLine` to prompt the user for a workspace name and then creates a new workspace with that name. It also showcases `wezterm.format` for colored text.

### Code
```lua
local wezterm = require 'wezterm'
local act = wezterm.action

local config = wezterm.config_builder()
config.keys = {
  {
    key = 'N',
    mods = 'CTRL|SHIFT',
    action = act.PromptInputLine {
      description = wezterm.format {
        { Attribute = { Intensity = 'Bold' } },
        { Foreground = { AnsiColor = 'Fuchsia' } },
        { Text = 'Enter name for new workspace' },
      },
      action = wezterm.action_callback(function(window, pane, line) 
        if line then
          window:perform_action(
            act.SwitchToWorkspace {
              name = line,
            },
            pane
          )
        end
      end),
    },
  },
}

return config
```
```

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

### Example: Toggling Window Opacity

Source: https://wezterm.org/config/lua/window/set_config_overrides.html

An example demonstrating how to use `window:set_config_overrides` to toggle window opacity on and off using a key binding.

```APIDOC
## Example: Toggling Window Opacity

### Description
This example shows how to assign a key combination (CTRL-SHIFT-B) to toggle the opacity of the current WezTerm window. It uses `window:get_config_overrides` to check the current override status and `window:set_config_overrides` to apply the desired opacity level or reset it.

### Method
`wezterm.on`, `window:get_config_overrides`, `window:set_config_overrides`, `wezterm.action.EmitEvent`

### Endpoint
N/A (Internal WezTerm API)

### Request Example
```lua
local wezterm = require 'wezterm'

wezterm.on('toggle-opacity', function(window, pane)
  local overrides = window:get_config_overrides() or {}
  if not overrides.window_background_opacity then
    overrides.window_background_opacity = 0.5
  else
    overrides.window_background_opacity = nil
  end
  window:set_config_overrides(overrides)
end)

return {
  keys = {
    {
      key = 'B',
      mods = 'CTRL', -- Note: The original text had 'CTRL' for 'B', but the example shows 'CTRL|SHIFT'. Assuming 'CTRL|SHIFT' is intended for the example.
      action = wezterm.action.EmitEvent 'toggle-opacity',
    },
  },
}
```

### Response
N/A (This is a configuration example that modifies window behavior.)
```

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

### Example Configuration for Workspace Switching

Source: https://wezterm.org/config/lua/keyassignment/SwitchWorkspaceRelative.html

This example demonstrates how to bind keyboard shortcuts to switch between workspaces using the `SwitchWorkspaceRelative` action. It also shows how to display the active workspace in the status bar.

```APIDOC
## Example Configuration

### Description
This configuration sets up keybindings for switching workspaces and displays the active workspace in the right-hand status bar.

### Method
`wezterm.on` and `config.keys`

### Endpoint
N/A (Configuration file settings)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```lua
local wezterm = require 'wezterm'
local act = wezterm.action

-- Display active workspace in the right status bar
wezterm.on('update-right-status', function(window, pane)
  window:set_right_status(window:active_workspace())
end)

-- Keybindings for workspace switching
config.keys = {
  -- Example: Show launcher with workspace fuzzy search
  {
    key = '9',
    mods = 'ALT',
    action = act.ShowLauncherArgs { flags = 'FUZZY|WORKSPACES' },
  },
  -- Switch to the next workspace
  { key = 'n', mods = 'CTRL', action = act.SwitchWorkspaceRelative(1) },
  -- Switch to the previous workspace
  { key = 'p', mods = 'CTRL', action = act.SwitchWorkspaceRelative(-1) },
}
```

### Response
#### Success Response (200)
None (This is a configuration example)

#### Response Example
None
```

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

### Example: Logging Font Size

Source: https://wezterm.org/config/lua/window/effective_config.html

This example demonstrates how to use `window:effective_config()` to access and log the current font size when a specific key combination is pressed.

```APIDOC
## Example: Logging Font Size

### Description
This example logs the configured font size when `CTRL-SHIFT-E` is pressed.

### Method
Lua Function

### Endpoint
N/A (Lua API)

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
Logs the font size to the WezTerm error log.

#### Response Example
```lua
local wezterm = require 'wezterm'

wezterm.on('show-font-size', function(window, pane) 
  wezterm.log_error(window:effective_config().font_size)
end)

return {
  keys = {
    { 
      key = 'E',
      mods = 'CTRL',
      action = wezterm.action.EmitEvent 'show-font-size',
    },
  },
}
```
```

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

### Example Configuration for ActivateTab

Source: https://wezterm.org/config/lua/keyassignment/ActivateTab.html

This example demonstrates how to configure keyboard shortcuts in WezTerm to use the ActivateTab function. It sets up CTRL+ALT + number keys and F1 through F8 keys to activate corresponding tabs.

```APIDOC
## Example Configuration

### Description
This configuration snippet shows how to bind keyboard shortcuts to the `ActivateTab` action. It includes bindings for `CTRL|ALT + number` and `F1` through `F8` keys to activate specific tabs.

### Method
`config.keys` table manipulation

### Endpoint
Not applicable (local configuration)

### Parameters
None

### Request Example
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {}
for i = 1, 8 do
  -- CTRL+ALT + number to activate that tab
  table.insert(config.keys, {
    key = tostring(i),
    mods = 'CTRL|ALT',
    action = act.ActivateTab(i - 1),
  })
  -- F1 through F8 to activate that tab
  table.insert(config.keys, {
    key = 'F' .. tostring(i),
    action = act.ActivateTab(i - 1),
  })
end

return config
```

### Response
#### Success Response (200)
Configuration is applied upon WezTerm restart.

#### Response Example
None
```

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

### Install a Wezterm Plugin

Source: https://wezterm.org/config/plugins.html

Basic implementation to load and apply a plugin to the Wezterm configuration.

```lua
local wezterm = require 'wezterm'
local a_plugin = wezterm.plugin.require 'https://github.com/owner/repo'

local config = wezterm.config_builder()

a_plugin.apply_to_config(config)

return config
```

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

### Configure hotkeys for window activation

Source: https://wezterm.org/config/lua/keyassignment/ActivateWindow.html

This example demonstrates how to map keyboard shortcuts to activate specific windows using a loop.

```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {}
for i = 1, 8 do
  -- CMD+ALT + number to activate that window
  table.insert(config.keys, {
    key = tostring(i),
    mods = 'CMD|ALT',
    action = act.ActivateWindow(i - 1),
  })
end

return config
```

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

### Example Usage in Status Bar

Source: https://wezterm.org/config/lua/wezterm/battery_info.html

An example demonstrating how to use `wezterm.battery_info()` to display battery status and the current date/time in the wezterm status bar.

```APIDOC
## Example: Update Right Status with Battery Info

### Description
This example shows how to update the right-side status bar in wezterm to display the battery level and the current date and time.

### Method
`wezterm.on('update-right-status', function(window, pane) ... end)`

### Endpoint
N/A (This is an event handler within wezterm)

### Parameters
- `window` (wezterm.Window) - The window object.
- `pane` (wezterm.Pane) - The pane object.

### Request Example
```lua
local wezterm = require 'wezterm'

wezterm.on('update-right-status', function(window, pane)
  -- "Wed Mar 3 08:14"
  local date = wezterm.strftime '%a %b %-d %H:%M '

  local bat = ''
  for _, b in ipairs(wezterm.battery_info()) do
    bat = '🔋 ' .. string.format('%.0f%%', b.state_of_charge * 100)
  end

  window:set_right_status(wezterm.format {
    { Text = bat .. '   ' .. date },
  })
end)
```

### Response
Updates the right status bar of the wezterm window with formatted text containing battery information and the current date/time. No direct return value from the event handler itself.
```

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

### Example: Displaying Active Workspace in Status Bar

Source: https://wezterm.org/config/lua/window/active_workspace.html

This example demonstrates how to use `window:active_workspace()` to display the active workspace name in the right status area of WezTerm. It also shows how to use the launcher menu to select and create workspaces.

```APIDOC
## Example: Displaying Active Workspace in Status Bar

### Description
This configuration snippet sets up a keybinding to open the launcher menu filtered for workspaces and configures the right status bar to display the name of the active workspace.

### Configuration
```lua
local wezterm = require 'wezterm'

-- Update the right status bar with the active workspace name
wezterm.on('update-right-status', function(window, pane)
  window:set_right_status(window:active_workspace())
end)

return {
  keys = {
    {
      key = '9',
      mods = 'ALT',
      -- Action to show the launcher menu, filtered for workspaces
      action = wezterm.action.ShowLauncherArgs { flags = 'FUZZY|WORKSPACES' },
    },
  },
}
```

### Remarks
- The `update-right-status` event is triggered whenever the status bar needs to be updated.
- The `ShowLauncherArgs` action with the `WORKSPACES` flag allows users to easily switch between or create new workspaces using the launcher.
- This example requires WezTerm version 20220319-142410-0fcdea07 or newer.
```

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

### Example: Choosing Canned Text

Source: https://wezterm.org/config/lua/keyassignment/InputSelector.html

An example demonstrating how to use InputSelector to allow the user to select predefined text to be sent to the terminal.

```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = wezterm.config_builder()

config.keys = {
  {
    key = 'E',
    mods = 'CTRL|SHIFT',
    action = act.InputSelector {
      action = wezterm.action_callback(function(window, pane, id, label) 
        if not id and not label then
          wezterm.log_info 'cancelled'
        else
          wezterm.log_info('you selected ', id, label)
          pane:send_text(id)
        end
      end),
      title = 'I am title',
      choices = {
        -- This is the first entry
        {
          -- Here we're using wezterm.format to color the text.
          -- You can just use a string directly if you don't want
          -- to control the colors
          label = wezterm.format {
            { Foreground = { AnsiColor = 'Red' } },
            { Text = 'No' },
            { Foreground = { AnsiColor = 'Green' } },
            { Text = ' thanks' },
          },
          -- This is the text that we'll send to the terminal when
          -- this entry is selected
          id = 'Regretfully, I decline this offer.',
        },
        -- This is the second entry
        {
          label = 'WTF?',
          id = 'An interesting idea, but I have some questions about it.',
        },
        -- This is the third entry
        {
          label = 'LGTM',
          id = 'This sounds like the right choice',
        },
      },
    },
  },
}

return config

```

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

### List Plugin Directories

Source: https://wezterm.org/config/plugins.html

Example output of the wezterm.plugin.list() function showing plugin metadata.

```json
[
    {
        "component": "filesCssZssZssZsUserssZsprojectssZsmysDsPlugin",
        "plugin_dir": "/Users/alec/Library/Application Support/wezterm/plugins/filesCssZssZssZsUserssZsalecsZsprojectssZsbarsDswezterm",
        "url": "file:///Users/developer/projects/my.Plugin",
    },
]
```

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

### Example: Toggling Font Ligatures

Source: https://wezterm.org/config/lua/window/set_config_overrides.html

An example demonstrating how to use `window:set_config_overrides` to toggle font ligatures on and off using a key binding.

```APIDOC
## Example: Toggling Font Ligatures

### Description
This example shows how to assign a key combination (CTRL-SHIFT-E) to toggle the use of ligatures in the current WezTerm window. It utilizes `window:get_config_overrides` to check the current state and `window:set_config_overrides` to apply the changes.

### Method
`wezterm.on`, `window:get_config_overrides`, `window:set_config_overrides`, `wezterm.action.EmitEvent`

### Endpoint
N/A (Internal WezTerm API)

### Request Example
```lua
local wezterm = require 'wezterm'

wezterm.on('toggle-ligature', function(window, pane)
  local overrides = window:get_config_overrides() or {}
  if not overrides.harfbuzz_features then
    -- If we haven't overridden it yet, then override with ligatures disabled
    overrides.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }
  else
    -- else we did already, and we should disable out override now
    overrides.harfbuzz_features = nil
  end
  window:set_config_overrides(overrides)
end)

return {
  keys = {
    {
      key = 'E',
      mods = 'CTRL', -- Note: The original text had 'CTRL' for 'E', but the example shows 'CTRL|SHIFT'. Assuming 'CTRL|SHIFT' is intended for the example.
      action = wezterm.action.EmitEvent 'toggle-ligature',
    },
  },
}
```

### Response
N/A (This is a configuration example that modifies window behavior.)
```

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

### Example Confirmation for Spawning htop

Source: https://wezterm.org/config/lua/keyassignment/Confirmation.html

Demonstrates how to use the Confirmation action to prompt the user before spawning 'htop' in a new window. Includes callbacks for both acceptance and cancellation.

```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = wezterm.config_builder()

config.keys = {
  {
    key = 'E',
    mods = 'CTRL|SHIFT',
    action = act.Confirmation {
      message = 'Do you want to run htop in a new window?',
      action = wezterm.action_callback(function(window, pane)
        window:perform_action(
          act.SpawnCommandInNewWindow { args = { 'htop' } },
          pane
        )
      end),
      cancel = wezterm.action_callback(function(window, pane)
        wezterm.log_error 'user declined'
      end),
    },
  },
}

return config

```

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

### Example SSH configuration file

Source: https://wezterm.org/config/lua/wezterm/enumerate_ssh_hosts.html

Sample ~/.ssh/config file demonstrating how Host stanzas are parsed; wildcard hosts are excluded by the function.

```text
Host aur.archlinux.org
  IdentityFile ~/.ssh/aur
  User aur

Host 192.168.1.*
  ForwardAgent yes
  ForwardX11 yes

Host woot
  User someone
  Hostname localhost
```

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

### Example: Opening Scrollback in Vim

Source: https://wezterm.org/config/lua/wezterm/on.html

This example demonstrates how to bind a key combination (Ctrl+E) to capture the entire scrollback and visible content of a pane, save it to a temporary file, and open it in Vim.

```APIDOC
## Example: Opening Whole Scrollback in Vim

### Description
This example configures a key binding (Ctrl+E) that captures the entire scrollback and visible content of the active pane, saves it to a temporary file, and then opens that file using the `vim` editor in a new window.

### Code
```lua
local wezterm = require 'wezterm'
local io = require 'io'
local os = require 'os'
local act = wezterm.action

wezterm.on('trigger-vim-with-scrollback', function(window, pane)
  -- Retrieve the text from the pane
  local text = pane:get_lines_as_text(pane:get_dimensions().scrollback_rows)

  -- Create a temporary file to pass to vim
  local name = os.tmpname()
  local f = io.open(name, 'w+')
  f:write(text)
  f:flush()
  f:close()

  -- Open a new window running vim and tell it to open the file
  window:perform_action(
    act.SpawnCommandInNewWindow {
      args = { 'vim', name },
    },
    pane
  )

  -- Wait for vim to read the file before removing it.
  wezterm.sleep_ms(1000)
  os.remove(name)
end)

return {
  keys = {
    {
      key = 'E',
      mods = 'CTRL',
      action = act.EmitEvent 'trigger-vim-with-scrollback',
    },
  },
}
```

### Explanation
- `wezterm.on('trigger-vim-with-scrollback', ...)`: Registers a custom event handler.
- `pane:get_lines_as_text(...)`: Retrieves the content from the pane's scrollback buffer.
- `os.tmpname()`: Creates a unique temporary filename.
- `io.open(...)`, `f:write(...)`, `f:close()`: Writes the captured text to the temporary file.
- `window:perform_action(act.SpawnCommandInNewWindow { ... })`: Spawns a new window running `vim` with the temporary file as an argument.
- `wezterm.sleep_ms(1000)` and `os.remove(name)`: Waits for a short period to allow `vim` to read the file, then removes the temporary file.
- `keys = { ... }`: Defines a key binding (Ctrl+E) that emits the `trigger-vim-with-scrollback` event.
```

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

### Example: Renaming Current Tab

Source: https://wezterm.org/config/lua/keyassignment/PromptInputLine.html

An example demonstrating how to use PromptInputLine to interactively rename the current tab.

```APIDOC
## Example: Renaming Current Tab

### Description
This example shows how to use `PromptInputLine` to get a new name for the current tab from the user and then set the tab's title.

### Code
```lua
local wezterm = require 'wezterm'
local act = wezterm.action

local config = wezterm.config_builder()
config.keys = {
  {
    key = 'E',
    mods = 'CTRL|SHIFT',
    action = act.PromptInputLine {
      description = 'Enter new name for tab',
      initial_value = 'My Tab Name',
      action = wezterm.action_callback(function(window, pane, line) 
        if line then
          window:active_tab():set_title(line)
        end
      end),
    },
  },
}

return config
```
```

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

### Define an ExecDomain with a static label

Source: https://wezterm.org/config/lua/ExecDomain.html

This example demonstrates defining an ExecDomain with a static string label that will appear in the Launcher Menu.

```lua
wezterm.exec_domain('myname', function(cmd)
  return cmd
end, 'My Custom Domain')
```

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

### Configure WSL default program

Source: https://wezterm.org/config/lua/wezterm/default_wsl_domains.html

Example of iterating through default WSL domains to set a custom default program for a specific distribution.

```lua
local wezterm = require 'wezterm'

local wsl_domains = wezterm.default_wsl_domains()

for idx, dom in ipairs(wsl_domains) do
  if dom.name == 'WSL:Ubuntu-18.04' then
    dom.default_prog = { 'fish' }
  end
end

return {
  wsl_domains = wsl_domains,
}
```

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

### Example: Random Color Scheme per Window

Source: https://wezterm.org/config/lua/wezterm.color/get_builtin_schemes.html

Demonstrates how to select and apply a random built-in color scheme to each newly created WezTerm window.

```APIDOC
## Example: Random Color Scheme per Window

### Description
This example shows how to make WezTerm pick a random color scheme for each newly created window.

### Method
N/A (Configuration Script)

### Endpoint
N/A (Configuration Script)

### Parameters
N/A

### Request Example
```lua
local wezterm = require 'wezterm'

-- The set of schemes that we like and want to put in our rotation
local schemes = {}
for name, scheme in pairs(wezterm.color.get_builtin_schemes()) do
  table.insert(schemes, name)
end

wezterm.on('window-config-reloaded', function(window, pane)
  -- If there are no overrides, this is our first time seeing
  -- this window, so we can pick a random scheme.
  if not window:get_config_overrides() then
    -- Pick a random scheme name
    local scheme = schemes[math.random(#schemes)]
    window:set_config_overrides {
      color_scheme = scheme,
    }
  end
end)

return {}
```

### Response
N/A (This is a configuration example, not an API response.)
```

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

### Install WezTerm Terminfo Data

Source: https://wezterm.org/config/lua/config/term.html

Download and install the wezterm.terminfo file to enable advanced terminal features like colored underlines, styled underlines, italics, and true color support. This command fetches the file, compiles it, and places it in the user's terminfo directory.

```bash
$ tempfile=$(mktemp) \
  && curl -o $tempfile https://raw.githubusercontent.com/wezterm/wezterm/main/termwiz/data/wezterm.terminfo \
  && tic -x -o ~/.terminfo $tempfile \
  && rm $tempfile

```

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

### Example: Select Dark Schemes Randomly

Source: https://wezterm.org/config/lua/wezterm.color/get_builtin_schemes.html

Demonstrates analyzing built-in schemes to identify dark ones and then randomly picking one for new windows.

```APIDOC
## Example: Select Dark Schemes Randomly

### Description
This example shows how to analyze the colors in the built-in schemes and use that to select just the dark schemes and then randomly pick one of those for each new window.

### Method
N/A (Configuration Script)

### Endpoint
N/A (Configuration Script)

### Parameters
N/A

### Request Example
```lua
local wezterm = require 'wezterm'

local function dark_schemes()
  local schemes = wezterm.color.get_builtin_schemes()
  local dark = {}
  for name, scheme in pairs(schemes) do
    -- parse into a color object
    local bg = wezterm.color.parse(scheme.background)
    -- and extract HSLA information
    local h, s, l, a = bg:hsla()

    -- `l` is the "lightness" of the color where 0 is darkest
    -- and 1 is lightest.
    if l < 0.4 then
      table.insert(dark, name)
    end
  end

  table.sort(dark)
  return dark
end

local dark = dark_schemes()

wezterm.on('window-config-reloaded', function(window, pane)
  -- If there are no overrides, this is our first time seeing
  -- this window, so we can pick a random scheme.
  if not window:get_config_overrides() then
    -- Pick a random scheme name

    local scheme = dark[math.random(#dark)]
    window:set_config_overrides {
      color_scheme = scheme,
    }
  end
end)

return {}
```

### Response
N/A (This is a configuration example, not an API response.)
```

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

### Example key event log output

Source: https://wezterm.org/config/lua/config/debug_key_events.html

Sample log output generated when debug_key_events is enabled, showing the structure of a KeyEvent.

```text
 2021-02-20T17:04:28.149Z INFO  wezterm_gui::gui::termwindow   > key_event 
   KeyEvent { key: Char('l'), modifiers: NONE, raw_key: None,
   raw_modifiers: NONE, raw_code: Some(46), repeat_count: 1, key_is_down: true }
 2021-02-20T17:04:28.605Z INFO  wezterm_gui::gui::termwindow   > key_event
   KeyEvent { key: Char('s'), modifiers: NONE, raw_key: None, raw_modifiers: NONE,
   raw_code: Some(39), repeat_count: 1, key_is_down: true }
```

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

### Launch program via CLI

Source: https://wezterm.org/config/launch.html

Use the start subcommand to launch a specific command in a new terminal window.

```bash
$ wezterm start -- vim ~/.wezterm.lua
```

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

### Spawn Command in New Tab with WezTerm

Source: https://wezterm.org/config/lua/keyassignment/SpawnCommandInNewTab.html

Configure a keybinding to open a new tab and execute a command. This example uses CMD-y to launch the 'top' process.

```lua
config.keys = {
  -- CMD-y starts `top` in a new tab
  {
    key = 'y',
    mods = 'CMD',
    action = wezterm.action.SpawnCommandInNewTab {
      args = { 'top' },
    },
  },
}
```

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

### Define ActivatePaneByIndex actions

Source: https://wezterm.org/config/lua/wezterm/action.html

Use the constructor syntax for tuple variants like ActivatePaneByIndex, passing positional parameters when calling the constructor. This example activates panes by their index.

```lua
local wezterm = require 'wezterm'
-- shortcut to save typing below
local act = wezterm.action

return {
  keys = {
    { key = 'F1', mods = 'ALT', action = act.ActivatePaneByIndex(0) },
    { key = 'F2', mods = 'ALT', action = act.ActivatePaneByIndex(1) },
    { key = 'F3', mods = 'ALT', action = act.ActivatePaneByIndex(2) },
    { key = 'F4', mods = 'ALT', action = act.ActivatePaneByIndex(3) },
    { key = 'F5', mods = 'ALT', action = act.ActivatePaneByIndex(4) },
    { key = 'F6', mods = 'ALT', action = act.ActivatePaneByIndex(5) },
    { key = 'F7', mods = 'ALT', action = act.ActivatePaneByIndex(6) },
    { key = 'F8', mods = 'ALT', action = act.ActivatePaneByIndex(7) },
    { key = 'F9', mods = 'ALT', action = act.ActivatePaneByIndex(8) },
    { key = 'F10', mods = 'ALT', action = act.ActivatePaneByIndex(9) },

    -- Compare this with the older syntax shown in the section below
    { key = '{', mods = 'CTRL', action = act.ActivateTabRelative(-1) },
    { key = '}', mods = 'CTRL', action = act.ActivateTabRelative(1) },
  },
}
```

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

### Example: Opening Scrollback in a Pager

Source: https://wezterm.org/config/lua/pane/get_lines_as_escapes.html

Demonstrates how to use `pane:get_lines_as_escapes` to capture the entire scrollback buffer and open it in a pager (like `less`) in a new window.

```APIDOC
## Example: Opening Scrollback in a Pager

### Description
This example sets up a keybinding to trigger an action that retrieves the entire scrollback buffer using `pane:get_lines_as_escapes`, saves it to a temporary file, and then opens that file in `less` within a new window. The temporary file is cleaned up after a short delay.

### Event Handler
```lua
local wezterm = require 'wezterm'
local io = require 'io'
local os = require 'os'
local act = wezterm.action

wezterm.on('trigger-less-with-scrollback', function(window, pane)
  -- Retrieve the current pane's text, including scrollback
  local text = pane:get_lines_as_escapes(pane:get_dimensions().scrollback_rows)

  -- Create a temporary file to pass to the pager
  local name = os.tmpname()
  local f = io.open(name, 'w+')
  f:write(text)
  f:flush()
  f:close()

  -- Open a new window running less and tell it to open the file
  window:perform_action(
    act.SpawnCommandInNewWindow {
      args = { 'less', '-fr', name },
    },
    pane
  )

  -- Wait for less to read the file before removing it.
  wezterm.sleep_ms(1000)
  os.remove(name)
end)
```

### Keybinding Configuration
```lua
return {
  keys = {
    {
      key = 'E',
      mods = 'CTRL',
      action = act.EmitEvent 'trigger-less-with-scrollback',
    },
  },
}
```
```

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

### Override WezTerm Window Title

Source: https://wezterm.org/config/lua/window-events/format-window-title.html

This example overrides the default window title by providing a custom string. It checks if the active pane is zoomed and if there are multiple tabs to format the title accordingly. This serves as a starting point for custom title configurations.

```lua
wezterm.on('format-window-title', function(tab, pane, tabs, panes, config)
  local zoomed = ''
  if tab.active_pane.is_zoomed then
    zoomed = '[Z] '
  end

  local index = ''
  if #tabs > 1 then
    index = string.format('[%d/%d] ', tab.tab_index + 1, #tabs)
  end

  return zoomed .. index .. tab.active_pane.title
end)

```

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

### Example terminal.sexy JSON structure

Source: https://wezterm.org/config/lua/wezterm.color/load_terminal_sexy_scheme.html

This is an example of the JSON structure exported from terminal.sexy that can be loaded by wezterm.

```json
{
  "name": "",
  "author": "",
  "color": [
    "#282a2e",
    "#a54242",
    "#8c9440",
    "#de935f",
    "#5f819d",
    "#85678f",
    "#5e8d87",
    "#707880",
    "#373b41",
    "#cc6666",
    "#b5bd68",
    "#f0c674",
    "#81a2be",
    "#b294bb",
    "#8abeb7",
    "#c5c8c6"
  ],
  "foreground": "#c5c8c6",
  "background": "#1d1f21"
}

```

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

### ShowLauncher Configuration

Source: https://wezterm.org/config/lua/keyassignment/ShowLauncher.html

Configuring a key binding to trigger the Launcher Menu in WezTerm.

```APIDOC
## ShowLauncher Action

### Description
Activates the Launcher Menu in the current tab.

### Configuration Example
```lua
config.keys = {
  { key = 'l', mods = 'ALT', action = wezterm.action.ShowLauncher },
}
```
```

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

### Configure Multiple Workspaces on Startup

Source: https://wezterm.org/config/lua/gui-events/gui-startup.html

This example sets up two distinct workspaces: 'coding' with an editor and build pane, and 'automation' for SSH access. It uses `wezterm.mux` to manage windows and tabs, and `wezterm.home_dir` to define project directories. The 'coding' workspace is set as the active one at the end.

```lua
local wezterm = require 'wezterm'
local mux = wezterm.mux
local config = {}

wezterm.on('gui-startup', function(cmd) 
  -- allow `wezterm start -- something` to affect what we spawn
  -- in our initial window
  local args = {}
  if cmd then
    args = cmd.args
  end

  -- Set a workspace for coding on a current project
  -- Top pane is for the editor, bottom pane is for the build tool
  local project_dir = wezterm.home_dir .. '/wezterm'
  local tab, build_pane, window = mux.spawn_window {
    workspace = 'coding',
    cwd = project_dir,
    args = args,
  }
  local editor_pane = build_pane:split {
    direction = 'Top',
    size = 0.6,
    cwd = project_dir,
  }
  -- may as well kick off a build in that pane
  build_pane:send_text 'cargo build\n'

  -- A workspace for interacting with a local machine that
  -- runs some docker containers for home automation
  local tab, pane, window = mux.spawn_window {
    workspace = 'automation',
    args = { 'ssh', 'vault' },
  }

  -- We want to startup in the coding workspace
  mux.set_active_workspace 'coding'
end)

return config

```

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

### Adding a New Tiling Environment

Source: https://wezterm.org/config/lua/config/tiling_desktop_environments.html

This example shows how to add a new tiling window environment, 'X11 awesome', to the default list. Consult the debug overlay to find the correct environment name.

```lua
"X11 awesome"
```

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

### Using wezterm.action Constructor (Modern Syntax)

Source: https://wezterm.org/config/lua/wezterm/action.html

Demonstrates the modern syntax for using `wezterm.action` to define key assignments, including unit variants and variants with parameters.

```APIDOC
## `wezterm.action` Constructor Syntax

### Description
This section details the constructor syntax for `wezterm.action`, which simplifies defining key assignment actions.

### Method
N/A (Configuration Script)

### Endpoint
N/A (Configuration Script)

### Parameters
N/A

### Request Example
```lua
local wezterm = require 'wezterm'
return {
  keys = {
    {
      key = ' ',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.QuickSelectArgs,
    },
  },
}
```

### Request Example with Arguments
```lua
local wezterm = require 'wezterm'
return {
  keys = {
    {
      key = ' ',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.QuickSelectArgs {
        alphabet = 'abc',
      },
    },
  },
}
```

### Request Example with Tuple Variant
```lua
local wezterm = require 'wezterm'
-- shortcut to save typing below
local act = wezterm.action

return {
  keys = {
    { key = 'F1', mods = 'ALT', action = act.ActivatePaneByIndex(0) },
    { key = '{', mods = 'CTRL', action = act.ActivateTabRelative(-1) },
    { key = '}', mods = 'CTRL', action = act.ActivateTabRelative(1) },
  },
}
```

### Response
N/A (Configuration Script)

### Response Example
N/A
```

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

### SpawnCommandInNewWindow Action

Source: https://wezterm.org/config/lua/keyassignment/SpawnCommandInNewWindow.html

Demonstrates how to use the `SpawnCommandInNewWindow` action to launch a command in a new WezTerm window. The action takes a `SpawnCommand` struct as an argument, which specifies the command and its arguments.

```APIDOC
## SpawnCommandInNewWindow Action

### Description
Spawns a new tab into a brand new window. The argument is a `SpawnCommand` struct.

### Method
N/A (Configuration Action)

### Endpoint
N/A (Configuration Action)

### Parameters
#### Request Body
- **SpawnCommand** (struct) - Required - A struct defining the command to spawn.
  - **args** (array of strings) - Required - The command and its arguments to execute.

### Request Example
```lua
config.keys = {
  -- CMD-y starts `top` in a new window
  {
    key = 'y',
    mods = 'CMD',
    action = wezterm.action.SpawnCommandInNewWindow {
      args = { 'top' },
    },
  },
}
```

### Response
N/A (Configuration Action)
```

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

### MoveTab Action Example

Source: https://wezterm.org/config/lua/keyassignment/MoveTab.html

This example demonstrates how to configure keyboard shortcuts to move tabs to specific positions using the `MoveTab` action. The `MoveTab(index)` action moves the current tab to the specified zero-based index. For instance, `MoveTab(0)` moves the tab to the leftmost position.

```APIDOC
## MoveTab Action

### Description

The `wezterm.action.MoveTab(index)` action allows you to move the currently active tab to a specified zero-based index. This is useful for organizing your workspace by rearranging tabs.

### Method

`wezterm.action.MoveTab(index)`

### Parameters

#### Path Parameters

*   **index** (number) - Required - The zero-based index to which the tab should be moved. `0` is the leftmost tab.

### Request Example

```lua
local wezterm = require 'wezterm'

-- Example of binding CTRL+ALT+1 to move the tab to the first position (index 0)
wezterm.on 'format-tab-title' (function(tab) 
  return tab.index .. ": " .. tab.active_pane.title
end)

wezterm.on 'user-entered-input' (function(window, key, mods) 
  if mods == 'CTRL|ALT' then
    local key_num = tonumber(key)
    if key_num and key_num >= 1 and key_num <= 8 then
      wezterm.action.MoveTab(key_num - 1)()
    end
  end
end)
```

### Response

This action does not return a value directly but modifies the state of the WezTerm window by repositioning the tab.
```

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

### GET pane:mux_pane()

Source: https://wezterm.org/config/lua/pane/mux_pane.html

Retrieves the MuxPane representation of the current pane.

```APIDOC
## GET pane:mux_pane()

### Description
Returns the MuxPane representation of this pane. In nightly versions of wezterm, there is no longer a distinction between gui and mux representations of panes, so this method returns itself.

### Since
Version 20220807-113146-c2fee766

### Deprecated
Since 20221119-145034-49b9839f
```

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

### Set default GUI startup arguments

Source: https://wezterm.org/config/lua/config/default_gui_startup_args.html

Configures the GUI to launch with specific arguments by default, such as initiating an SSH session.

```lua
config.default_gui_startup_args = { 'ssh', 'some-host' }
```

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

### Bind ShowLauncher to a key

Source: https://wezterm.org/config/lua/keyassignment/ShowLauncher.html

Assigns the Alt+l key combination to open the launcher menu within the configuration file.

```lua
config.keys = {
  { key = 'l', mods = 'ALT', action = wezterm.action.ShowLauncher },
}
```

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

### Check WSL distributions

Source: https://wezterm.org/config/lua/wezterm/default_wsl_domains.html

Command to list installed WSL distributions via the terminal.

```bash
; wsl -l -v
  NAME            STATE           VERSION
* Ubuntu-18.04    Running         1
```

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

### GET window:get_config_overrides()

Source: https://wezterm.org/config/lua/window/get_config_overrides.html

Retrieves a copy of the current configuration overrides applied to the window.

```APIDOC
## GET window:get_config_overrides()

### Description
Returns a copy of the current set of configuration overrides that is in effect for the window.

### Method
GET

### Endpoint
window:get_config_overrides()

### Response
- **overrides** (table) - A copy of the current configuration overrides applied to the window.
```

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

### Pad a string to the left

Source: https://wezterm.org/config/lua/wezterm/pad_left.html

Example usage of wezterm.pad_left to pad a single character to a width of 3.

```lua
wezterm.pad_left("o", 3)
```

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

### Initialize WezTerm Configuration

Source: https://wezterm.org/config/lua/general.html

Basic template for importing the wezterm module and setting a font configuration.

```lua
local wezterm = require 'wezterm'
local config = {}
config.font = wezterm.font 'JetBrains Mono'
return config
```

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

### PastePrimarySelection Action

Source: https://wezterm.org/config/lua/keyassignment/PastePrimarySelection.html

Configuration examples for binding the PastePrimarySelection action to keyboard shortcuts or mouse events.

```APIDOC
## PastePrimarySelection

### Description
Pastes the X11 Primary Selection to the current tab. On non-X11 systems, this behaves identically to the Paste action.

### Status
- Deprecated: Version 20210203-095643-70a364eb
- Removed: Version 20230320-124340-559cb7b0
- Recommendation: Use `PasteFrom` instead.

### Example
```lua
local wezterm = require 'wezterm'
local act = wezterm.action

config.keys = {
  { key = 'v', mods = 'SHIFT|CTRL', action = act.PastePrimarySelection },
}

-- Middle mouse button pastes the primary selection.
config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Middle' } },
    mods = 'NONE',
    action = act.PastePrimarySelection,
  },
}
```
```

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

### Handling GUI Events

Source: https://wezterm.org/config/lua/gui-events/index.html

Documentation for the gui-attached and gui-startup events emitted by the WezTerm GUI.

```APIDOC
## GUI Events

### Description
The WezTerm GUI emits specific lifecycle events that can be intercepted using the `wezterm.on` function.

### Events
- **gui-attached**: Emitted when the GUI is attached to a terminal session.
- **gui-startup**: Emitted when the GUI application is starting up.

### Usage Example
```lua
wezterm.on('gui-startup', function(cmd)
  -- Custom logic here
end)

wezterm.on('gui-attached', function(window)
  -- Custom logic here
end)
```
```

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

### Get Workspace Names

Source: https://wezterm.org/config/lua/wezterm.mux/get_workspace_names.html

Retrieves a table containing the names of all workspaces known to the WezTerm multiplexer.

```APIDOC
## `wezterm.mux.get_workspace_names()`

### Description
Returns a table containing the names of the workspaces known to the mux.

### Method
`GET` (conceptual, as this is a function call within WezTerm's Lua API)

### Endpoint
N/A (Lua API function)

### Parameters
None

### Request Example
```lua
local workspace_names = wezterm.mux.get_workspace_names()
print(workspace_names)
```

### Response
#### Success Response
- `table` - A Lua table where each element is a string representing a workspace name.

#### Response Example
```json
{
  "example": "{ 'workspace1', 'workspace2', 'default' }"
}
```

### Notes
- Requires WezTerm version 20220624-141144-bd1b7c5d or newer.
```

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

### WSL domain object structure

Source: https://wezterm.org/config/lua/wezterm/default_wsl_domains.html

Example return value structure for the default WSL domains function.

```lua
{
  {
    name: "WSL:Ubuntu-18.04",
    distribution: "Ubuntu-18.04",
  },
}
```

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

### Basic WezTerm Configuration in Lua

Source: https://wezterm.org/config/files.html

Set initial window dimensions, font size, and color scheme using wezterm.config_builder(). Ensure the configuration is returned to wezterm.

```lua
-- Pull in the wezterm API
local wezterm = require 'wezterm'

-- This will hold the configuration.
local config = wezterm.config_builder()

-- This is where you actually apply your config choices.

-- For example, changing the initial geometry for new windows:
config.initial_cols = 120
config.initial_rows = 28

-- or, changing the font size and color scheme.
config.font_size = 10
config.color_scheme = 'AdventureTime'

-- Finally, return the configuration to wezterm:
return config

```

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

### Maximize Initial Window on Startup

Source: https://wezterm.org/config/lua/gui-events/gui-startup.html

This snippet maximizes the initial window upon startup. It requires the `wezterm` and `wezterm.mux` modules.

```lua
local wezterm = require 'wezterm'
local mux = wezterm.mux
local config = {}

wezterm.on('gui-startup', function(cmd) 
  local tab, pane, window = mux.spawn_window(cmd or {})
  window:gui_window():maximize()
end)

return config

```

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

### Retrieve screen information via Debug Overlay

Source: https://wezterm.org/config/lua/wezterm.gui/screens.html

Example output of the wezterm.gui.screens() function when executed in the Debug Overlay.

```lua
> wezterm.gui.screens()
{
    "active": {
        "height": 1800,
        "name": "Built-in Retina Display",
        "width": 2880,
        "x": 0,
        "y": 0,
    },
    "by_name": {
        "Built-in Retina Display": {
            "height": 1800,
            "name": "Built-in Retina Display",
            "width": 2880,
            "x": 0,
            "y": 0,
        },
    },
    "main": {
        "height": 1800,
        "name": "Built-in Retina Display",
        "width": 2880,
        "x": 0,
        "y": 0,
    },
    "origin_x": 0,
    "origin_y": 0,
    "virtual_height": 1800,
    "virtual_width": 2880,
}
```