162 lines
4.2 KiB
Markdown
162 lines
4.2 KiB
Markdown
---
|
|
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
|