WezTerm

https://wezterm.org
Admin
WezTerm is a powerful cross-platform terminal emulator and multiplexer written in Rust that supports...
Tokens:1,627,906
Snippets:6,779
Trust Score:8.3
Update:5 days ago
Show doc for...
Tokens:
Raw
### wezterm start usage and options

Source: https://wezterm.org/cli/start.html?q=

Shows the full help output for `wezterm start`, including the usage line, the PROG argument with alias -e, and all options such as --no-auto-connect, --always-new-process, --new-tab, --cwd, --class, --workspace, --position, --domain, --attach, and -h/--help. The example `wezterm start -- bash -l` spawns bash as a login shell.

```text
Start the GUI, optionally running an alternative program [aliases: -e]

Usage: wezterm start [OPTIONS] [PROG]...

Arguments:
  [PROG]...
          Instead of executing your shell, run PROG. For example: `wezterm start
          -- bash -l` will spawn bash as if it were a login shell. [aliases: -e]

Options:
      --no-auto-connect
          If true, do not connect to domains marked as connect_automatically in
          your wezterm configuration file

      --always-new-process
          If enabled, don't try to ask an existing wezterm GUI instance to start
          the command.  Instead, always start the GUI in this invocation of
          wezterm so that you can wait for the command to complete by waiting
          for this wezterm process to finish

      --new-tab
          When spawning into an existing GUI instance, spawn a new tab into the
          active window rather than spawn a new window

      --cwd <CWD>
          Specify the current working directory for the initially spawned
          program

      --class <CLASS>
          Override the default windowing system class. The default is
          "org.wezfurlong.wezterm". Under X11 and Windows this changes the
          window class. Under Wayland this changes the app_id. This changes the
          class for all windows spawned by this instance of wezterm, including
          error, update and ssh authentication dialogs

      --workspace <WORKSPACE>
          Override the default workspace with the provided name. The default is
          "default"

      --position <POSITION>
          Override the position for the initial window launched by this process.

          --position 10,20          to set x=10, y=20 in screen coordinates
          --position screen:10,20   to set x=10, y=20 in screen coordinates
          --position main:10,20     to set x=10, y=20 relative to the main
          monitor
          --position active:10,20   to set x=10, y=20 relative to the active
          monitor
          --position HDMI-1:10,20   to set x=10, y=20 relative to the monitor
          named HDMI-1

          Note that Wayland does not allow applications to control window
          positioning.

      --domain <DOMAIN>
          Name of the multiplexer domain section from the configuration to which
          you'd like to connect. If omitted, the default domain will be used

      --attach
          When used with --domain, if the domain already has running panes,
          wezterm will simply attach and will NOT spawn the specified PROG. If
          you omit --attach when using --domain, wezterm will attach AND then
          spawn PROG

  -h, --help
          Print help (see a summary with '-h')

```

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

### 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' },
  },
}

```

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

### Install WezTerm with Scoop

Source: https://wezterm.org/install/windows.html

Add the Extras bucket and install WezTerm using Scoop. Requires Scoop to be installed first.

```shell
$ scoop bucket add extras
$ scoop install wezterm

```

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

### Install WezTerm via APT

Source: https://wezterm.org/install/linux.html

Installs the stable version of WezTerm using apt.

```bash
$ sudo apt install wezterm

```

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

### Install WezTerm on openSUSE (dnf install)

Source: https://wezterm.org/install/linux.html?q=

Installs WezTerm after enabling the Copr repository. Requires the previous step to have been completed.

```bash
$ sudo dnf install wezterm

```

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

### Install WezTerm on openSUSE

Source: https://wezterm.org/install/linux.html

Installs dnf, enables the WezTerm nightly Copr repository, and installs WezTerm. Replace <repository> with the appropriate repository for your flavor and architecture.

```bash
$ sudo zypper in dnf
$ sudo dnf copr enable wezfurlong/wezterm-nightly <repository>

```

```bash
$ sudo dnf install wezterm

```

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

### Install WezTerm with winget

Source: https://wezterm.org/install/windows.html

Use winget to install WezTerm from the command line. Requires winget, which is part of the App Installer from the Microsoft Store.

```shell
$ winget install wez.wezterm

```

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

### Install WezTerm from GitHub Release

Source: https://wezterm.org/install/linux.html

Downloads and installs a specific WezTerm RPM package from GitHub releases. This example installs the Fedora 39 package.

```bash
$ sudo dnf install -y https://github.com/wezterm/wezterm/releases/download/20240203-110809-5046fc22/wezterm-20240203_110809_5046fc22-1.fedora39.x86_64.rpm

```

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

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

```

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

### Start neovim with WezTerm terminfo

Source: https://wezterm.org/faq.html

Command to start neovim with the WezTerm terminal type, enabling undercurl support after installing the terminfo file.

```bash
env TERM=wezterm nvim

```

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

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

```

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

### Use WezTerm flake with home-manager (flake.nix)

Source: https://wezterm.org/install/linux.html

Example flake.nix for home-manager configuration using the WezTerm flake.

```nix
# flake.nix

{
    inputs.wezterm.url = "github:wezterm/wezterm?dir=nix";
    # ...

    outputs = inputs @ {nixpkgs, home-manager, ...}:{
        homeConfigurations."user@HOSTNAME" = home-manager.lib.homeManagerConfiguration {
            pkgs = nixpkgs.legacyPackages.x86_64-linux;
            extraSpecialArgs = { inherit inputs; }; # Pass inputs to homeManagerConfiguration
            modules = [
                ./home.nix
            ];
        };        
    };
}

```

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

### wezterm.to_string example in Lua

Source: https://wezterm.org/config/lua/wezterm/to_string.html?q=

Shows how to use wezterm.to_string to get a string representation of Lua tables. The example asserts that the output for an array-like table is a multi-line list, and for a key-value table it is a JSON-like object. The format is not guaranteed to be stable across versions.

```lua
local wezterm = require 'wezterm'
assert(wezterm.to_string { 1, 2 } == [=[[
    1,
    2,
]]=])
assert(wezterm.to_string { a = 1, b = 2 } == [[{
    "a": 1,
    "b": 2,
}]])

```

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

### wezterm.log_error usage example

Source: https://wezterm.org/config/lua/wezterm/log_error.html?q=

Logs the string 'Hello!' at ERROR level. Requires wezterm version 20210814-124438-54e29167 or later. The message appears in the debug overlay or stdout if started from a terminal.

```lua
local wezterm = require 'wezterm'
wezterm.log_error 'Hello!'

```

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

### Build from full git repository

Source: https://wezterm.org/install/source.html

Commands to install Rust, clone the full git repository with submodules, install dependencies, and build and run WezTerm. Use this if you plan to contribute to the project.

```bash
$ curl https://sh.rustup.rs -sSf | sh -s
$ git clone --depth=1 --branch=main --recursive https://github.com/wezterm/wezterm.git
$ cd wezterm
$ git submodule update --init --recursive
$ ./get-deps
$ cargo build --release
$ cargo run --release --bin wezterm -- start
```

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

### Maximize initial window on gui-startup

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

Creates a default window and maximizes it on startup using `window:gui_window():maximize()`. The window is spawned with `mux.spawn_window(cmd or {})`.

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

```

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

### Convert color to linear RGBA and print values

Source: https://wezterm.org/config/lua/color/linear_rgba.html?q=

Parses the color 'purple' and calls linear_rgba() to get a tuple of linear RGBA values. The example prints the returned values, showing the output in the log.

```lua
> r, g, b, a = wezterm.color.parse("purple"):linear_rgba()
> print(r, g, b, a)
07:32:17.734 INFO logging > lua: 0.2158605307340622 0 0.2158605307340622 1
```

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

### List clients with JSON output

Source: https://wezterm.org/cli/cli/list-clients.html?q=

Use `--format json` to get machine-readable output. The example shows the JSON structure with fields like username, hostname, pid, connection_elapsed, idle_time, workspace, and focused_pane_id.

```bash
$ wezterm cli list-clients --format json
[
  {
    "username": "wez",
    "hostname": "foo",
    "pid": 1098536,
    "connection_elapsed": {
      "secs": 226,
      "nanos": 502667166
    },
    "idle_time": {
      "secs": 0,
      "nanos": 502667166
    },
    "workspace": "default",
    "focused_pane_id": 0
  }
]

```

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

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

```

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

### Configure APT repository for WezTerm

Source: https://wezterm.org/install/linux.html

Adds the WezTerm APT repository and sets up the signing key.

```bash
$ curl -fsSL https://apt.fury.io/wez/gpg.key | sudo gpg --yes --dearmor -o /usr/share/keyrings/wezterm-fury.gpg
$ echo 'deb [signed-by=/usr/share/keyrings/wezterm-fury.gpg] https://apt.fury.io/wez/ * *' | sudo tee /etc/apt/sources.list.d/wezterm.list
$ sudo chmod 644 /usr/share/keyrings/wezterm-fury.gpg

```

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

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

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

### Example output of wezterm show-keys

Source: https://wezterm.org/cli/show-keys.html

Truncated example of the output showing the default key table, copy_mode, search_mode, and mouse bindings. The output is formatted with key modifiers and actions.

```text
Default key table
-----------------

        CTRL                 Tab                ->   ActivateTabRelative(1)
        SHIFT | CTRL         Tab                ->   ActivateTabRelative(-1)
        ...

Key Table: copy_mode
--------------------

                Tab          ->   CopyMode(MoveForwardWord)
        SHIFT   Tab          ->   CopyMode(MoveBackwardWord)
        SHIFT   $            ->   CopyMode(MoveToEndOfLineContent)
        ...

Key Table: search_mode
----------------------

               Enter       ->   CopyMode(PriorMatch)
               Escape      ->   CopyMode(Close)
        CTRL   n           ->   CopyMode(NextMatch)
        ...

Mouse
-----

                       Down { streak: 1, button: Left }     ->   SelectTextAtMouseCursor(Cell)
        SHIFT          Down { streak: 1, button: Left }     ->   ExtendSelectionToMouseCursor(None)
        ALT            Down { streak: 1, button: Left }     ->   SelectTextAtMouseCursor(Block)
        ...

```

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

### Configure two workspaces on gui-startup

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

Sets up two workspaces: 'coding' with an editor and build pane, and 'automation' for SSH. Uses `mux.spawn_window` with workspace, cwd, and args. Starts a build in the build pane and activates the 'coding' workspace.

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

```

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

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

```

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

### wezterm cli spawn synopsis

Source: https://wezterm.org/cli/cli/spawn.html

Full command-line help for `wezterm cli spawn`, including usage, arguments, and options.

```text
Spawn a command into a new window or tab
Outputs the pane-id for the newly created pane on success

Usage: wezterm cli spawn [OPTIONS] [PROG]...

Arguments:
  [PROG]...  Instead of executing your shell, run PROG. For example: `wezterm
             cli spawn -- bash -l` will spawn bash as if it were a login shell

Options:
      --pane-id <PANE_ID>
          Specify the current pane. The default is to use the current pane based
          on the environment variable WEZTERM_PANE. The pane is used to
          determine the current domain and window
      --domain-name <DOMAIN_NAME>

      --window-id <WINDOW_ID>
          Specify the window into which to spawn a tab. If omitted, the window
          associated with the current pane is used. Cannot be used with
          `--workspace` or `--new-window`
      --new-window
          Spawn into a new window, rather than a new tab
      --cwd <CWD>
          Specify the current working directory for the initially spawned
          program
      --workspace <WORKSPACE>
          When creating a new window, override the default workspace name with
          the provided name.  The default name is "default". Requires
          `--new-window`
  -h, --help
          Print help

```
Tokens:
Raw