---
title: "WezTerm — Launching Programs"
aliases: [wezterm-launch, wezterm-default-prog, wezterm-launcher-menu]
tags: [wezterm, terminal, shell, launch, config]
sources: [raw/Launching Programs - Wez's Terminal Emulator.md]
created: 2026-04-17
updated: 2026-04-17
---

## Overview

WezTerm resolves which program to spawn for new tabs/windows using a clear priority chain. You can override the default at config level, per-invocation via CLI, or interactively via the Launcher Menu.

---

## Shell Resolution Order

WezTerm deliberately **ignores `$SHELL`** and reads the password database instead, so a shell change takes effect without restarting WezTerm.

- **Unix:** password database entry for the current user → spawned as `-<SHELL>` (login shell)
- **Windows (fallback):** `%COMSPEC%` → `cmd.exe`

WezTerm then sets `$SHELL` itself. To override the value downstream, use `set_environment_variables`:

```lua
config.set_environment_variables = {
  SHELL = "/opt/homebrew/bin/fish",
}
```

---

## Changing the Default Program

```lua
-- Spawn fish in login mode for every new tab/window
config.default_prog = { '/usr/local/bin/fish', '-l' }
```

---

## One-Off Programs via CLI

```sh
# Open a new WezTerm window running vim
wezterm start -- vim ~/.wezterm.lua

# Start in a specific directory
wezterm start --cwd /some/path
```

---

## Working Directory (CWD) Resolution

Priority order for new panes/tabs:

1. **OSC 7** escape sequence reported by the shell (most reliable — requires shell integration)
2. CWD of current process group leader (local panes only)
3. `default_cwd` config value
4. User home directory

```lua
config.default_cwd = "/some/path"
```

For [[wiki/dotfiles/wezterm-cli-reference|SpawnCommand]] objects (key bindings, launcher menu):

```lua
{
  label = "List files in /some/path",
  args  = { "ls", "-al" },
  cwd   = "/some/path",
}
```

---

## Environment Variables

`set_environment_variables` inherits WezTerm's own env then overlays your values:

```lua
config.set_environment_variables = {
  -- OSC 7 prompt for cmd.exe (Windows)
  prompt = '$E]7;file://localhost/$P$E\\$E[32m$T$E[0m $E[35m$P$E[36m$_$G$E[0m ',
}
```

---

## Launcher Menu

Accessed by **right-clicking** the `+` button in the tab bar, or via a key binding mapped to `ShowLauncher` / `ShowLauncherArgs`.

Each entry is a `SpawnCommand` object:

```lua
config.launch_menu = {
  { args = { 'top' } },
  {
    label = 'Bash',
    args  = { 'bash', '-l' },
    -- cwd = "/some/path",
    -- set_environment_variables = { FOO = "bar" },
  },
}
```

### Dynamic Windows Entries Example

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

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

---

## Key Takeaways

- WezTerm ignores `$SHELL` — it reads the password database; set `set_environment_variables` if you need to override downstream
- `config.default_prog` replaces the default shell for all new tabs/windows
- `wezterm start -- <cmd>` launches a one-off program from the CLI
- CWD inherits via OSC 7 → process group → `default_cwd` → home; shell integration is the most reliable path
- The Launcher Menu (right-click `+`) is extensible with `config.launch_menu` using `SpawnCommand` objects
- Windows users can dynamically populate the menu using `wezterm.glob` + `wezterm.target_triple`

---

## Related

- [[wiki/dotfiles/wezterm-config|WezTerm Config — Files & Structure]]
- [[wiki/dotfiles/wezterm-cli-reference|WezTerm CLI Reference]]
- [[wiki/dotfiles/wezterm-key-bindings|WezTerm Key Bindings]]
- [[wiki/dotfiles/fish-shell-intro|Fish Shell Intro]]

---

## Sources

- `raw/Launching Programs - Wez's Terminal Emulator.md` — scraped from wezterm.org/config/launch.html