WezTerm

https://wezterm.org/config/
Admin
WezTerm is a GPU-accelerated cross-platform terminal emulator that supports multiplexing, SSH, and...
Tokens:194,093
Snippets:1,453
Trust Score:8.3
Update:2 days ago
Show doc for...
Tokens:
Raw
### wezterm.on('mux-startup') - spawn window and split top/bottom

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

Use this event to start a set of programs in a standard configuration. The example creates a window and splits it top/bottom. If any panes are created, they take precedence over the default program configuration.

```lua
local wezterm = require 'wezterm'
local mux = wezterm.mux

-- this is called by the mux server when it starts up.
-- It makes a window split top/bottom
wezterm.on('mux-startup', function()
  local tab, pane, window = mux.spawn_window {}
  pane:split { direction = 'Top' }
end)

return {
  unix_domains = {
    { name = 'unix' },
  },
}

```

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

### wezterm.gui.screens() example output

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

Example output from the Debug Overlay (CTRL-SHIFT-L) on a macbook, showing the structure of the returned table with active, main, by_name, and virtual desktop geometry keys.

```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,
}

```

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

### Launch vim via wezterm start CLI

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

Use the wezterm start subcommand to launch a one-off program in a new terminal window. This example opens vim to edit the wezterm configuration.

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

```

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

### wezterm key_tables example: leader key for pane resize and activation

Source: https://wezterm.org/config/key-tables.html

This example defines a leader key (CTRL+SHIFT+Space) that activates two named key tables: 'resize_pane' and 'activate_pane'. The 'resize_pane' table uses one_shot=false and includes an Escape key to pop the table, while 'activate_pane' uses a timeout of 1000ms. The example also shows how to display the active key table in the status area.

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

-- Show which key table is active in the status area
wezterm.on('update-right-status', function(window, pane)
  local name = window:active_key_table()
  if name then
    name = 'TABLE: ' .. name
  end
  window:set_right_status(name or '')
end)

config.leader = { key = 'Space', mods = 'CTRL|SHIFT' }
config.keys = {
  -- CTRL+SHIFT+Space, followed by 'r' will put us in resize-pane
  -- mode until we cancel that mode.
  {
    key = 'r',
    mods = 'LEADER',
    action = act.ActivateKeyTable {
      name = 'resize_pane',
      one_shot = false,
    },
  },

  -- CTRL+SHIFT+Space, followed by 'a' will put us in activate-pane
  -- mode until we press some other key or until 1 second (1000ms)
  -- of time elapses
  {
    key = 'a',
    mods = 'LEADER',
    action = act.ActivateKeyTable {
      name = 'activate_pane',
      timeout_milliseconds = 1000,
    },
  },
}

config.key_tables = {
  -- Defines the keys that are active in our resize-pane mode.
  -- Since we're likely to want to make multiple adjustments,
  -- we made the activation one_shot=false. We therefore need
  -- to define a key assignment for getting out of this mode.
  -- 'resize_pane' here corresponds to the name="resize_pane" in
  -- the key assignments above.
  resize_pane = {
    { key = 'LeftArrow', action = act.AdjustPaneSize { 'Left', 1 } },
    { key = 'h', action = act.AdjustPaneSize { 'Left', 1 } },

    { key = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } },
    { key = 'l', action = act.AdjustPaneSize { 'Right', 1 } },

    { key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } },
    { key = 'k', action = act.AdjustPaneSize { 'Up', 1 } },

    { key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } },
    { key = 'j', action = act.AdjustPaneSize { 'Down', 1 } },

    -- Cancel the mode by pressing escape
    { key = 'Escape', action = 'PopKeyTable' },
  },

  -- Defines the keys that are active in our activate-pane mode.
  -- 'activate_pane' here corresponds to the name="activate_pane" in
  -- the key assignments above.
  activate_pane = {
    { key = 'LeftArrow', action = act.ActivatePaneDirection 'Left' },
    { key = 'h', action = act.ActivatePaneDirection 'Left' },

    { key = 'RightArrow', action = act.ActivatePaneDirection 'Right' },
    { key = 'l', action = act.ActivatePaneDirection 'Right' },

    { key = 'UpArrow', action = act.ActivatePaneDirection 'Up' },
    { key = 'k', action = act.ActivatePaneDirection 'Up' },

    { key = 'DownArrow', action = act.ActivatePaneDirection 'Down' },
    { key = 'j', action = act.ActivatePaneDirection 'Down' },
  },
}

return config

```

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

### Example: Automatic Color Scheme Adjustment

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

Example configuration showing how to automatically adjust the color scheme based on the current appearance using the window-config-reloaded event.

```APIDOC
## Example: Automatic Color Scheme Adjustment

### Description
This example configuration shows how to have your color scheme automatically adjust to the current appearance using the `window-config-reloaded` event.

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

function scheme_for_appearance(appearance)
  if appearance:find 'Dark' then
    return 'Builtin Solarized Dark'
  else
    return 'Builtin Solarized Light'
  end
end

wezterm.on('window-config-reloaded', function(window, pane)
  local overrides = window:get_config_overrides() or {}
  local appearance = window:get_appearance()
  local scheme = scheme_for_appearance(appearance)
  if overrides.color_scheme ~= scheme then
    overrides.color_scheme = scheme
    window:set_config_overrides(overrides)
  end
end)

return {}
```
```

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

### wezterm.shell_join_args examples

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

Shows two example invocations of wezterm.shell_join_args with their outputs. The first joins 'foo' and 'bar' to produce 'foo bar'. The second joins 'hello there' and 'you', quoting the argument containing a space, producing '"hello there" you'.

```lua
> wezterm.shell_join_args{"foo", "bar"}
"foo bar"
> wezterm.shell_join_args{"hello there", "you"}
"\"hello there\" you"

```

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

### Example logs for zsh spawning bash spawning vim

Source: https://wezterm.org/config/lua/mux-events/mux-is-process-stateful.html

Shows the output produced by the example handler for a process tree where zsh spawned bash, which spawned vim foo. Each line includes the log prefix, pid, name, status, argv, executable, and cwd, with indentation indicating hierarchy depth.

```text
INFO  config::lua > lua: pid=1913470, name=zsh, status=Sleep
INFO  config::lua > lua: argv=-zsh
INFO  config::lua > lua: executable=/usr/bin/zsh, cwd=/home/wez
INFO  config::lua > lua:   pid=1913567, name=bash, status=Sleep
INFO  config::lua > lua:   argv=bash
INFO  config::lua > lua:   executable=/usr/bin/bash, cwd=/home/wez
INFO  config::lua > lua:     pid=1913624, name=vim, status=Sleep
INFO  config::lua > lua:     argv=vim foo
INFO  config::lua > lua:     executable=/usr/bin/vim, cwd=/home/wez

```

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

### Example: Using foreground_process_name in format-tab-title

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

Example showing how to use the foreground_process_name field to display the executable name in tab titles.

```APIDOC
## Example: Using foreground_process_name in format-tab-title

### Description
This example places the executable name in the tab titles using the foreground_process_name field.

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

-- Equivalent to POSIX basename(3)
-- Given "/foo/bar" returns "bar"
-- Given "c:\\foo\\bar" returns "bar"
function basename(s)
  return string.gsub(s, '(.*[/\\])(.*)', '%2')
end

wezterm.on(
  'format-tab-title',
  function(tab, tabs, panes, config, hover, max_width)
    local pane = tab.active_pane
    local title = basename(pane.foreground_process_name)
      .. ' '
      .. pane.pane_id
    local color = 'navy'
    if tab.is_active then
      color = 'blue'
    end
    return {
      { Background = { Color = color } },
      { Text = ' ' .. title .. ' ' },
    }
  end
)

return {}
```
```

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

### SplitPane key assignment example

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

Example key assignment that creates a new split to the left and runs the 'top' program. Uses Ctrl+Shift+Alt+% and sets the split size to 50%.

```lua
config.keys = {
  -- This will create a new split and run the `top` program inside it
  {
    key = '%',
    mods = 'CTRL|SHIFT|ALT',
    action = wezterm.action.SplitPane {
      direction = 'Left',
      command = { args = { 'top' } },
      size = { Percent = 50 },
    },
  },
}
```

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

### List WSL distributions with `wsl -l -v`

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

Command to list available WSL distributions and their states. The output shows an example with Ubuntu-18.04 running.

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

```

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

### wezterm.color.gradient example in REPL

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

Example of calling wezterm.color.gradient with a preset gradient and 4 colors, as shown in the debug overlay REPL. The output is a table of color strings.

```lua
> wezterm.color.gradient({preset="Rainbow"}, 4)
["#6e40aa", "#ff8c38", "#5dea8d", "#6e40aa"]
```

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

### Returned WslDomain list from default_wsl_domains

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

Example of the list returned by wezterm.default_wsl_domains(), showing a WslDomain with name and distribution fields.

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

```

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

### Example: wezterm.time.now():sun_times(33.44, -112)

Source: https://wezterm.org/config/lua/wezterm.time/Time/sun_times.html

Computes sun times for Phoenix, Arizona. Returns a table with rise, set, up, and progression. The example shows the sun is up (up == true) and 41% through the day. At the poles, rise and set are nil, progression is 0, and up indicates polar day or night.

```lua
> wezterm.time.now():sun_times(33.44, -112)
{
    "progression": 0.41843971631205673,
    "rise": "Time(utc: 2022-07-17T12:29:42.493449687+00:00)",
    "set": "Time(utc: 2022-07-18T02:36:40.776247739+00:00)",
    "up": true,
}

```

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

### Set webgpu_preferred_adapter to first GPU

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

Uses wezterm.gui.enumerate_gpus() to get the list of GPUs and selects the first one as the preferred adapter. Requires front_end = 'WebGpu'.

```lua
local wezterm = require 'wezterm'
local config = {}
local gpus = wezterm.gui.enumerate_gpus()

config.webgpu_preferred_adapter = gpus[1]
config.front_end = 'WebGpu'
return config

```

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

### wezterm.gradient_colors REPL example

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

Example of calling wezterm.gradient_colors in the debug overlay REPL with a preset gradient and 4 colors, showing the returned table of color strings.

```lua
> wezterm.gradient_colors({preset="Rainbow"}, 4)
["#6e40aa", "#ff8c38", "#5dea8d", "#6e40aa"]

```

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

### WezTerm font_rules configuration example

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

Example configuration that sets a base font and defines font_rules to handle bold, italic, and dim text with specific font weights and a custom foreground color. The rules are processed in order, and the first matching rule overrides the base font.

```lua
config.font = wezterm.font_with_fallback 'Operator Mono SSm Lig Medium'
config.font_rules = {
  -- For Bold-but-not-italic text, use this relatively bold font, and override
  -- its color to a tomato-red color to make bold text really stand out.
  {
    intensity = 'Bold',
    italic = false,
    font = wezterm.font_with_fallback(
      'Operator Mono SSm Lig',
      -- Override the color specified by the terminal output and force
      -- it to be tomato-red.
      -- The color value you set here can be any CSS color name or
      -- RGB color string.
      { foreground = 'tomato' }
    ),
  },

  -- Bold-and-italic
  {
    intensity = 'Bold',
    italic = true,
    font = wezterm.font_with_fallback {
      family = 'Operator Mono SSm Lig',
      italic = true,
    },
  },

  -- normal-intensity-and-italic
  {
    intensity = 'Normal',
    italic = true,
    font = wezterm.font_with_fallback {
      family = 'Operator Mono SSm Lig',
      weight = 'DemiLight',
      italic = true,
    },
  },

  -- half-intensity-and-italic (half-bright or dim); use a lighter weight font
  {
    intensity = 'Half',
    italic = true,
    font = wezterm.font_with_fallback {
      family = 'Operator Mono SSm Lig',
      weight = 'Light',
      italic = true,
    },
  },

  -- half-intensity-and-not-italic
  {
    intensity = 'Half',
    italic = false,
    font = wezterm.font_with_fallback {
      family = 'Operator Mono SSm Lig',
      weight = 'Light',
    },
  },
}

```

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

### Using wezterm.action.QuickSelectArgs as a unit variant

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

For unit variants like QuickSelectArgs, you can reference the constructor directly without extra punctuation. This example binds CTRL+SHIFT+SPACE to the default QuickSelectArgs action.

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

```

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

### Confirmation example: run htop in new window

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

Binds CTRL+SHIFT+E to a Confirmation prompt. If the user accepts, it spawns htop in a new window; if declined, it logs an error. Requires a nightly build of WezTerm.

```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

```

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

### Quick Start: .wezterm.lua configuration

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

Create a file named `.wezterm.lua` in your home directory with this content to set initial geometry, font size, and color scheme. The configuration is built using `wezterm.config_builder()` and returned at the end.

```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

```

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

### Format current UTC date/time with wezterm.strftime_utc

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

Use wezterm.strftime_utc with a format string to get the current UTC date/time. The example formats as '%Y-%m-%d %H:%M:%S' and logs the result. Requires wezterm version 20220624-141144-bd1b7c5d or newer.

```lua
local wezterm = require 'wezterm'

local date_and_time = wezterm.strftime_utc '%Y-%m-%d %H:%M:%S'
wezterm.log_info(date_and_time)

```

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

### Parse color and print srgba_u8 components

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

Use wezterm.color.parse to get a color object, then call srgba_u8() to obtain the red, green, blue, and alpha components as unsigned 8-bit integers. The example prints the tuple, showing the output for the color 'purple' as 128 0 128 255.

```lua
> r, g, b, a = wezterm.color.parse("purple"):srgba_u8()
> print(r, g, b, a)
07:30:20.045 INFO logging > lua: 128 0 128 255
```

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

### Adjust font size based on hostname using wezterm.hostname()

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

Use wezterm.hostname() to get the current hostname and conditionally set configuration values, such as font_size. The example checks if the hostname is 'pixelbookgo-localdomain' and uses a larger font size on that host, otherwise a smaller one. Note that hostname may be unreliable in DHCP environments with short leases.

```lua
local wezterm = require 'wezterm'
local hostname = wezterm.hostname()

local font_size
if hostname == 'pixelbookgo-localdomain' then
  -- Use a bigger font on the smaller screen of my PixelBook Go
  font_size = 12.0
else
  font_size = 10.0
end

return {
  font_size = font_size,
}

```

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

### Custom hyperlink_rules examples

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

Shows how to start from the default rules and add custom rules: making task numbers clickable and making username/project paths clickable as GitHub links. The task number rule uses the first capture group in the format string. The GitHub path rule matches quoted or unquoted paths and uses capture groups $1 and $3.

```lua
-- Use the defaults as a base
config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- make task numbers clickable
-- the first matched regex group is captured in $1.
table.insert(config.hyperlink_rules, {
  regex = [[\b[tt](\d+)\b]],
  format = 'https://example.com/tasks/?t=$1',
})

-- make username/project paths clickable. this implies paths like the following are for github.
-- ( "nvim-treesitter/nvim-treesitter" | wbthomason/packer.nvim | wezterm/wezterm | "wezterm/wezterm.git" )
-- as long as a full url hyperlink regex exists above this it should not match a full url to
-- github or gitlab / bitbucket (i.e. https://gitlab.com/user/project.git is still a whole clickable url)
table.insert(config.hyperlink_rules, {
  regex = [[["]?([\w\d]{1}[-\w\d]+)(/){1}([-\w\d\.]+)["]?]],
  format = 'https://www.github.com/$1/$3',
})

```

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

### Example: Using domain_name in format-tab-title

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

Example showing how to use the domain_name field to append the domain name to the tab title.

```APIDOC
## Example: Using domain_name in format-tab-title

### Description
This example shows the domain name of the active pane appended to the tab title.

### Code
```lua
local wezterm = require 'wezterm'
local config = {}

wezterm.on('format-tab-title', function(tab)
  local pane = tab.active_pane
  local title = pane.title
  if pane.domain_name then
    title = title .. ' - (' .. pane.domain_name .. ')'
  end
  return title
end)

return config
```
```

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

### Example: Using has_unseen_output in format-tab-title

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

Example showing how to use the has_unseen_output field to change the tab color when there is unseen output.

```APIDOC
## Example: Using has_unseen_output in format-tab-title

### Description
This example shows how to use the has_unseen_output field to change the color of the tab in the tab bar when there is unseen output.

### Code
```lua
local wezterm = require 'wezterm'
local config = {}

wezterm.on(
  'format-tab-title',
  function(tab, tabs, panes, config, hover, max_width)
    if tab.is_active then
      return {
        { Background = { Color = 'blue' } },
        { Text = ' ' .. tab.active_pane.title .. ' ' },
      }
    end
    local has_unseen_output = false
    for _, pane in ipairs(tab.panes) do
      if pane.has_unseen_output then
        has_unseen_output = true
        break
      end
    end
    if has_unseen_output then
      return {
        { Background = { Color = 'Orange' } },
        { Text = ' ' .. tab.active_pane.title .. ' ' },
      }
    end
    return tab.active_pane.title
  end
)

return config
```
```

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

### Spawn a new window with default program

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

Spawns a program into a new window with no arguments, using the default program. Returns the MuxTab, Pane, and MuxWindow objects.

```lua
local tab, pane, window = wezterm.mux.spawn_window {}

```

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

### Example: Polling Appearance on Wayland

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

Example configuration for older WezTerm versions on Wayland that polls the appearance using the update-right-status event.

```APIDOC
## Example: Polling Appearance on Wayland

### Description
This example shows how to automatically adjust the color scheme on Wayland for older WezTerm versions by polling the appearance using the `update-right-status` event.

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

function scheme_for_appearance(appearance)
  if appearance:find 'Dark' then
    return 'Builtin Solarized Dark'
  else
    return 'Builtin Solarized Light'
  end
end

wezterm.on('update-right-status', function(window, pane)
  local overrides = window:get_config_overrides() or {}
  local appearance = query_appearance_gnome()
  local scheme = scheme_for_appearance(appearance)
  if overrides.color_scheme ~= scheme then
    overrides.color_scheme = scheme
    window:set_config_overrides(overrides)
  end
end)

return {}
```
```

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

### wezterm.mux.spawn_window{}

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

Spawns a program into a new window, returning the MuxTab, Pane, and MuxWindow objects. Supports optional parameters to control the spawned program and window.

```APIDOC
## wezterm.mux.spawn_window{}

### Description
Spawns a program into a new window, returning the MuxTab, Pane, and MuxWindow objects associated with it. When no arguments are passed, the default program is spawned.

### Method
Function call

### Endpoint
wezterm.mux.spawn_window{}

### Parameters
#### Optional Parameters
- **args** (table) - Optional - Specifies the argument array for the command that should be spawned. If omitted, the default program for the domain will be spawned.
- **cwd** (string) - Optional - Specify the current working directory that should be used for the program. If unspecified, follows the rules from default_cwd.
- **set_environment_variables** (table) - Optional - Sets additional environment variables in the environment for this command invocation.
- **domain** (table) - Optional - Specifies the multiplexer domain into which the program should be spawned. The default value is assumed to be `"DefaultDomain"`. You may specify the name of one of the multiplexer domains defined in your configuration using `{ DomainName = 'my.name' }`.
- **width** (number) - Optional - Only valid when used together with height, allows specifying the number of column cells that the window should have.
- **height** (number) - Optional - Only valid when used together with width, allows specifying the number of row cells that the window should have.
- **workspace** (table) - Optional - Specifies the name of the workspace that the newly created window will be associated with. If omitted, the currently active workspace name will be used.
- **position** (table) - Optional - Specify the initial position for the GUI window that will be created to display this mux window. The value is a lua table with fields `x`, `y`, and optional `origin`.

### Request Example
```lua
local tab, pane, window = wezterm.mux.spawn_window {}
```

### Response
#### Success Response
Returns the MuxTab, Pane, and MuxWindow objects associated with the new window.

#### Response Example
```lua
local tab, pane, window = wezterm.mux.spawn_window {}
```

```

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

### Spawn a window with args parameter

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

Specifies the argument array for the command to spawn. If omitted, the default program for the domain is spawned.

```lua
wezterm.mux.spawn_window { args = { 'top' } }

```

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

### wezterm.serde.toml_decode example

Source: https://wezterm.org/config/lua/wezterm.serde/toml_decode.html

Parses a TOML string and returns the equivalent Lua values. The example shows the function call and its output. Requires a nightly build of wezterm.

```lua
> wezterm.serde.toml_decode('foo = "bar"')
{
    "foo": "bar",
}
```

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

### Example: get_info_for_pid with pid() and output

Source: https://wezterm.org/config/lua/wezterm.procinfo/get_info_for_pid.html

Shows how to call wezterm.procinfo.get_info_for_pid with the current process ID and the resulting LocalProcessInfo object. The output includes fields such as argv, children, cwd, executable, name, pid, ppid, start_time, and status. The function may return nil if it cannot retrieve the info.

```lua
> wezterm.procinfo.get_info_for_pid(wezterm.procinfo.pid())
{
    "argv": [
        "/home/wez/wez-personal/wezterm/target/debug/wezterm-gui",
    ],
    "children": {
        540513: {
            "argv": [
                "-zsh",
            ],
            "children": {},
            "cwd": "/home/wez",
            "executable": "/usr/bin/zsh",
            "name": "zsh",
            "pid": 540513,
            "ppid": 540450,
            "start_time": 232656896,
            "status": "Sleep",
        },
    },
    "cwd": "/home/wez/wez-personal/wezterm",
    "executable": "/home/wez/wez-personal/wezterm/target/debug/wezterm-gui",
    "name": "wezterm-gui",
    "pid": 540450,
    "ppid": 425276,
    "start_time": 8671498240,
    "status": "Run",
}

```

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

### ShowLauncherArgs

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

Activates the Launcher Menu in the current tab, scoping it to a set of items and with an optional title. The arguments are a lua table with keys: flags (required), title (optional), help_text, fuzzy_help_text, and alphabet.

```APIDOC
## ShowLauncherArgs

### Description
Activates the Launcher Menu in the current tab, scoping it to a set of items and with an optional title.

### Arguments
- **flags** (string) - Required - The set of flags that specifies what to show in the launcher. Flags can be joined with `|`.
- **title** (string) - Optional - The title to show in the tab while the launcher is active.
- **help_text** (string) - Optional - A string to display when in the default mode. Defaults to: `"Select an item and press Enter=launch  Esc=cancel  /=filter"` (Since: Nightly Builds Only)
- **fuzzy_help_text** (string) - Optional - A string to display when in fuzzy finding mode. Defaults to: `"Fuzzy matching: "` (Since: Nightly Builds Only)
- **alphabet** (string) - Optional - A string of unique characters used to calculate one or two key press shortcuts for quick selection in default mode. Defaults to the same value as launcher_alphabet (Since: Nightly Builds Only)

### Flags
- `"FUZZY"` - Activate in fuzzy-only mode.
- `"TABS"` - Include the list of tabs from the current window.
- `"LAUNCH_MENU_ITEMS"` - Include the launch_menu items.
- `"DOMAINS"` - Include multiplexing domains.
- `"KEY_ASSIGNMENTS"` - Include items taken from your key assignments.
- `"WORKSPACES"` - Include workspaces.
- `"COMMANDS"` - Include a number of default commands (Since: Version 20220408-101518-b908e2dd).

### Example
```lua
config.keys = {
  {
    key = '9',
    mods = 'ALT',
    action = wezterm.action.ShowLauncherArgs { flags = 'FUZZY|TABS' },
  },
}
```
```

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

### TlsDomainClient configuration fields example

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

Shows all available fields for the TlsDomainClient struct with comments explaining each option. Use this as a reference for configuring TLS clients. Note that fields like pem_private_key, pem_cert, pem_ca, pem_root_certs, accept_invalid_hostnames, expected_cn, connect_automatically, read_timeout, write_timeout, and remote_wezterm_path are optional and commented out.

```lua
config.tls_clients = {
  {
    -- The name of this specific domain.  Must be unique amongst
    -- all types of domain in the configuration file.
    name = 'server.name',

    -- If set, use ssh to connect, start the server, and obtain
    -- a certificate.
    -- The value is "user@host:port", just like "wezterm ssh" accepts.
    bootstrap_via_ssh = 'server.hostname',

    -- identifies the host:port pair of the remote server.
    remote_address = 'server.hostname:8080',

    -- the path to an x509 PEM encoded private key file.
    -- Omit this if you are using `bootstrap_via_ssh`.
    -- pem_private_key = "/some/path/key.pem",

    -- the path to an x509 PEM encoded certificate file
    -- Omit this if you are using `bootstrap_via_ssh`.
    -- pem_cert = "/some/path/cert.pem",

    -- the path to an x509 PEM encoded CA chain file
    -- Omit this if you are using `bootstrap_via_ssh`.
    -- pem_ca = "/some/path/ca.pem",

    -- A set of paths to load additional CA certificates.
    -- Each entry can be either the path to a directory or to a PEM encoded
    -- CA file.  If an entry is a directory, then its contents will be
    -- loaded as CA certs and added to the trust store.
    -- Omit this if you are using `bootstrap_via_ssh`.
    -- pem_root_certs = { "/some/path/ca1.pem", "/some/path/ca2.pem" },

    -- explicitly control whether the client checks that the certificate
    -- presented by the server matches the hostname portion of
    -- `remote_address`.  The default is true.  This option is made
    -- available for troubleshooting purposes and should not be used outside
    -- of a controlled environment as it weakens the security of the TLS
    -- channel.
    -- accept_invalid_hostnames = false,

    -- the hostname string that we expect to match against the common name
    -- field in the certificate presented by the server.  This defaults to
    -- the hostname portion of the `remote_address` configuration and you
    -- should not normally need to override this value.
    -- expected_cn = "other.name",

    -- If true, connect to this domain automatically at startup
    -- connect_automatically = false,

    -- Specify an alternate read timeout
    -- read_timeout = 60,

    -- Specify an alternate write timeout
    -- write_timeout = 60,

    -- The path to the wezterm binary on the remote host
    -- remote_wezterm_path = "/home/myname/bin/wezterm"
  },
}

```

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

### Full colors configuration example

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

Defines a complete color palette using the `colors` section. Supports SVG/CSS3 color names and hex codes like `#RRGGBB`. Includes cursor, selection, scrollbar, split, ANSI, brights, indexed, compose, copy mode, quick select, input selector, and launcher colors. Some options are marked as Nightly Builds Only.

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

config.colors = {
  -- The default text color
  foreground = 'silver',
  -- The default background color
  background = 'black',

  -- Overrides the cell background color when the current cell is occupied by the
  -- cursor and the cursor style is set to Block
  cursor_bg = '#52ad70',
  -- Overrides the text color when the current cell is occupied by the cursor
  cursor_fg = 'black',
  -- Specifies the border color of the cursor when the cursor style is set to Block,
  -- or the color of the vertical or horizontal bar when the cursor style is set to
  -- Bar or Underline.
  cursor_border = '#52ad70',

  -- the foreground color of selected text
  selection_fg = 'black',
  -- the background color of selected text
  selection_bg = '#fffacd',

  -- The color of the scrollbar "thumb"; the portion that represents the current viewport
  scrollbar_thumb = '#222222',

  -- The color of the split lines between panes
  split = '#444444',

  ansi = {
    'black',
    'maroon',
    'green',
    'olive',
    'navy',
    'purple',
    'teal',
    'silver',
  },
  brights = {
    'grey',
    'red',
    'lime',
    'yellow',
    'blue',
    'fuchsia',
    'aqua',
    'white',
  },

  -- Arbitrary colors of the palette in the range from 16 to 255
  indexed = { [136] = '#af8700' },

  -- Since: 20220319-142410-0fcdea07
  -- When the IME, a dead key or a leader key are being processed and are effectively
  -- holding input pending the result of input composition, change the cursor
  -- to this color to give a visual cue about the compose state.
  compose_cursor = 'orange',

  -- Override the foreground color for composition/IME preview text,
  -- such as text being dictated via macOS dictation or composed via
  -- a dead key sequence. Falls back to the cursor foreground color.
  compose_fg = '#1e1e2e', -- (*Since: Nightly Builds Only*)

  -- Override the background color for composition/IME preview text.
  -- Falls back to the cursor background color.
  compose_bg = '#f5c2e7', -- (*Since: Nightly Builds Only*)

  -- Colors for copy_mode and quick_select
  -- available since: 20220807-113146-c2fee766
  -- In copy_mode, the color of the active text is:
  -- 1. copy_mode_active_highlight_* if additional text was selected using the mouse
  -- 2. selection_* otherwise
  copy_mode_active_highlight_bg = { Color = '#000000' },
  -- use `AnsiColor` to specify one of the ansi color palette values
  -- (index 0-15) using one of the names "Black", "Maroon", "Green",
  --  "Olive", "Navy", "Purple", "Teal", "Silver", "Grey", "Red", "Lime",
  -- "Yellow", "Blue", "Fuchsia", "Aqua" or "White".
  copy_mode_active_highlight_fg = { AnsiColor = 'Black' },
  copy_mode_inactive_highlight_bg = { Color = '#52ad70' },
  copy_mode_inactive_highlight_fg = { AnsiColor = 'White' },

  quick_select_label_bg = { Color = 'peru' },
  quick_select_label_fg = { Color = '#ffffff' },
  quick_select_match_bg = { AnsiColor = 'Navy' },
  quick_select_match_fg = { Color = '#ffffff' },

  input_selector_label_bg = { AnsiColor = 'Black' }, -- (*Since: Nightly Builds Only*)
  input_selector_label_fg = { Color = '#ffffff' }, -- (*Since: Nightly Builds Only*)

  launcher_label_bg = { AnsiColor = 'Black' }, -- (*Since: Nightly Builds Only*)
  launcher_label_fg = { Color = '#ffffff' }, -- (*Since: Nightly Builds Only*)
}

return config

```

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

### Using color:square() to get square colors

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

Calls square() on a parsed color to get the three other colors 90 degrees apart on the HSL color wheel. Requires wezterm version 20220807-113146-c2fee766 or newer.

```lua
local a, b, c = wezterm.color.parse("yellow"):square()

```

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

### Using color:triad() to get triad colors

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

Parses the color 'yellow' and calls triad() to get the other two colors at +/- 120 degrees in the HSL color wheel. Requires wezterm version 20220807-113146-c2fee766 or later.

```lua
local a, b = wezterm.color.parse('yellow'):triad()

```

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

### Add Windows-specific launcher entries (PowerShell and VS prompts)

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

Builds a launch_menu table conditionally for Windows (x86_64-pc-windows-msvc). Adds a PowerShell entry and scans for installed Visual Studio versions to add 'x64 Native Tools' command prompts. Returns the launch_menu in the config table.

```lua
local wezterm = require 'wezterm'
local launch_menu = {}

if wezterm.target_triple == 'x86_64-pc-windows-msvc' then
  table.insert(launch_menu, {
    label = 'PowerShell',
    args = { 'powershell.exe', '-NoLogo' },
  })

  -- Find installed visual studio version(s) and add their compilation
  -- environment command prompts to the menu
  for _, vsvers in
    ipairs(
      wezterm.glob('Microsoft Visual Studio/20*', 'C:/Program Files (x86)')
    )
  do
    local year = vsvers:gsub('Microsoft Visual Studio/', '')
    table.insert(launch_menu, {
      label = 'x64 Native Tools VS ' .. year,
      args = {
        'cmd.exe',
        '/k',
        'C:/Program Files (x86)/'
          .. vsvers
          .. '/BuildTools/VC/Auxiliary/Build/vcvars64.bat',
      },
    })
  end
end

return {
  launch_menu = launch_menu,
}
```

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

### Lua example: format-tab-title with progress

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

A Lua configuration example that uses tab.active_pane.progress to style tab titles with Nerd Fonts circle glyphs and color (green for percentage, red for error). It registers a format-tab-title event and returns a config_builder.

```lua
local wezterm = require 'wezterm'

local function tab_title(tab_info)
  local title = tab_info.tab_title
  -- if the tab title is explicitly set, take that
  if title and #title > 0 then
    return title
  end
  -- Otherwise, use the title from the active pane
  -- in that tab
  return tab_info.active_pane.title
end

local PCT_GLYPHS = {
  wezterm.nerdfonts.md_circle_slice_1,
  wezterm.nerdfonts.md_circle_slice_2,
  wezterm.nerdfonts.md_circle_slice_3,
  wezterm.nerdfonts.md_circle_slice_4,
  wezterm.nerdfonts.md_circle_slice_5,
  wezterm.nerdfonts.md_circle_slice_6,
  wezterm.nerdfonts.md_circle_slice_7,
  wezterm.nerdfonts.md_circle_slice_8,
}
local function pct_glyph(pct)
  local slot = math.floor(pct / 12)
  return PCT_GLYPHS[slot + 1]
end

wezterm.on(
  'format-tab-title',
  function(tab, tabs, panes, config, hover, max_width)
    local progress = tab.active_pane.progress or 'None'
    local title = tab_title(tab)
    local elements = {
      { Text = string.format('%d: ', tab.tab_index + 1) },
    }

    if progress ~= 'None' then
      local color = 'green'
      local status
      if progress.Percentage ~= nil then
        -- status = string.format("%d%%", progress.Percentage)
        status = pct_glyph(progress.Percentage)
      elseif progress.Error ~= nil then
        -- status = string.format("%d%%", progress.Error)
        status = pct_glyph(progress.Error)
        color = 'red'
      elseif progress == 'Indeterminate' then
        status = '~'
      else
        status = wezterm.serde.json_encode(progress)
      end

      table.insert(elements, { Foreground = { Color = color } })
      table.insert(elements, { Text = status })
      table.insert(elements, { Foreground = 'Default' })
    end

    table.insert(elements, { Text = ' ' .. title .. ' ' })

    return elements
  end
)

return wezterm.config_builder()

```

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

### wezterm.plugin.list()

Source: https://wezterm.org/config/lua/wezterm.plugin/list.html

Returns a table array listing all plugin repositories in the plugin directory. Each entry contains the URL, component name, and absolute plugin directory path.

```APIDOC
## wezterm.plugin.list()

### Description
Returns a table array listing all plugin repositories in the plugin directory.

### Method
Function call

### Endpoint
wezterm.plugin.list()

### Parameters
None

### Return Value
A table array where each entry has the following fields:
- **url** (string) - The URL of the plugin repo, as provided to the `wezterm.plugin.require` function.
- **component** (string) - The encoded name of the plugin, derived from the repo URL.
- **plugin_dir** (string) - The absolute location of the plugin checkout in the Wezterm runtime directory. Use this to set the plugin path if needed.

### Example
```lua
local plugins = wezterm.plugin.list()
for _, plugin in ipairs(plugins) do
  print(plugin.url, plugin.component, plugin.plugin_dir)
end
```
```

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

### Set font with wezterm.font

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

Use wezterm.font to specify a font face. The first example sets 'Fira Code' with default style. The second example selects 'JetBrains Mono' with Bold weight and italic style. Both are shown in the same code block.

```lua
config.font = wezterm.font 'Fira Code'
-- You can specify some parameters to influence the font selection;
-- for example, this selects a Bold, Italic font variant.
config.font =
  wezterm.font('JetBrains Mono', { weight = 'Bold', italic = true })
```
Tokens:
Raw