obsidian/wiki/dotfiles/wezterm-launching-programs.md at d4504b68d1bcaa88d00a3ecb63ab4be098f87f3d

Vadym/obsidian

Fork 0

Vadym Samoilenko 64e4b78afa vault backup: 2026-04-17 12:58:17

2026-04-17 12:58:17 +01:00

4.2 KiB

Raw Blame History

title

aliases

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:

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

Changing the Default Program

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

One-Off Programs via CLI

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

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

config.default_cwd = "/some/path"

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

{
  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:

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

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:

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

Dynamic Windows Entries Example

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

Sources

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

4.2 KiB Raw Blame History