WezTerm's "debug overlay" tips and tricks thread

[mattmc3]

I started using WezTerm for the first time yesterday, and it's been wonderful! How have I not known about this amazing tool? I started rebuilding my iTerm2 config into a WezTerm config and was instantly productive... until I wasn't. Enter Ctrl + Shift + L - the Debug Overlay for troubleshooting!

As a new user to both WezTerm and lua, the docs are great, but I could have really used a starter guide to the debugger, so that's what this thread is for - for the community to share any debugger tips you have.

While working through the debugger to learn how to get at my config values (issue #4238), here's what I discovered.

Tip 0: It's just a lua REPL

You can write any lua statement you want. It doesn't have to be WezTerm related. Enter the debug overlay with Ctrl + Shift + L, and exit with Esc or Ctrl + D:

> -- comments start with a double dash
> -- math works
> 1 + 2 + 2 + 1
6
> -- variable assignment
> cluemath = 1 + 2 + 1 + 1  -- scarlet
> cluemath  -- print by just typing the variable
5

You can learn more about lua here.

Tip 1: The debugger saves history

The debugger stores your history. You can use Ctrl + r to search it just like Bash history, or hit the up arrow to cycle back. On my Mac, the history file was here:

$ # Notice this example is in Bash, not the lua REPL
$ tail -n 20 ~/Library/Application\ Support/wezterm/repl-history

Tip 3: You can access WezTerm modules

You can see (and interact with) all the modules wezterm provides. For example, let's look at the wezterm.time module:

> wezterm.time
{
    "call_after": function: 0x6000036d16b0,
    "now": function: 0x6000036d2f40,
    "parse": function: 0x6000036d0150,
    "parse_rfc3339": function: 0x6000036d2940,
}
> -- call the now function
> wezterm.time.now()
Time(utc: 2024-08-18T11:43:38.517242+00:00)

You can use this concept to do things like view the hex color codes used for the built-in color schemes:

> schemes = wezterm.get_builtin_color_schemes()
> schemes["tokyonight"]
{
    "ansi": [
        "#15161e",
        "#f7768e",
        "#9ece6a",
        "#e0af68",
        "#7aa2f7",
        "#bb9af7",
        "#7dcfff",
        "#a9b1d6",
    ],
...
}

Tip 4: You can view your config

The window object is also exposed, which lets you interact with the current GUI window. Notice that with window, we call methods with colon :, not dot .. You can read why here.

> window  -- Show the window object
GuiWin(mux_window_id:0, pid:99835)
> -- Get the current in-force config by calling the effective_config() func
> myconfig = window:effective_config()
> -- Show my font configuration
> myconfig["font"]
{
    "font": [
        {
            "family": "MesloLGM Nerd Font Mono",
            "is_fallback": false,
            "is_synthetic": false,
            "stretch": "Normal",
            "style": "Normal",
            "weight": "Regular",
        },
    ],
}

Tip 5: Putting it all together

Remember, it's all just lua, so you can make a function:

-- Get all the keys from a table (dictionary)
function get_keys(t)
  local keys={}
  for key,_ in pairs(t) do
    table.insert(keys, key)
  end
  table.sort(keys)
  return keys
end

Now, show all the available config keys:

> get_keys(myconfig)
[
    "allow_download_protocols",
    "allow_square_glyphs_to_overflow_width",
    "allow_win32_input_mode",
    "alternate_buffer_wheel_scroll_speed",
    "animation_fps",
    "anti_alias_custom_block_glyphs",
    "audible_bell",
...
    "window_decorations",
    "window_frame",
    "window_padding",
]

This is the thread I wish I had had to fast track me, so I started one. Hopefully it can help other users new to the built-in debugger. Are there other debugger tips you have that you wish you'd known when you started using WezTerm? Comment below.