wezterm/docs/config/launch.md

Launching Programs

By default, when opening new tabs or windows, your shell will be spawned.

Your shell is determined by the following rules:

=== "On Posix Systems"

1. The value of the `$SHELL` environment variable is used if it is set
2. Otherwise, it will resolve your current uid and try to look up your
shell from the password database.

`wezterm` will spawn the shell and pass `-l` as an argument to request
a login shell.  A login shell generally loads additional startup files
and sets up more environment than a non-login shell.

{{since('20210502-154244-3f7122cb', inline=True)}}: instead of passing `-l` to the shell, wezterm
will spawn the shell as `-$SHELL` to invoke it as a login shell.

Note: if you have recently changed your shell using `chsh` and you
have `$SHELL` set in the environment, you will need to sign out and
sign back in again for the environment to pick up your new `$SHELL`
value.

{{since('20220903-194523-3bb1ed61', inline=True)}}: wezterm will now always resolve the shell via the
password database.

=== "On Windows Systems"

1. The value of the `%COMSPEC%` environment variable is used if it is set.
2. Otherwise, `cmd.exe`

Changing the default program

If you'd like wezterm to run a different program than the shell as described above, you can use the default_prog config setting to specify the argument array; the array allows specifying the program and arguments portably:

-- Spawn a fish shell in login mode
config.default_prog = { '/usr/local/bin/fish', '-l' }

Launching a different program as a one off via the CLI

If you want to make a shortcut for your desktop environment that will, for example, open an editor in wezterm you can use the start subcommand to launch it. This example opens up a new terminal window running vim to edit your wezterm configuration:

$ wezterm start -- vim ~/.wezterm.lua

Specifying the current working directory

If you'd like wezterm to start running a program in a specific working directory you can do so via the config, CLI, and when using SpawnCommand:

• Setting the default_cwd via the config:

  config.default_cwd = "/some/path"
  

• One off program in a specific working directory via the CLI:

  $ wezterm start --cwd /some/path
  

• The SpawnCommandInNewTab, and SpawnCommandInNewWindow key assignments, and the Launcher Menu described below all accept a SpawnCommand object that accepts an optional cwd field:

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

Panes/Tabs/Windows created after the first will generally try to resolve the current working directory of the current Pane, preferring a value set by OSC 7 and falling back to attempting to lookup the cwd of the current process group leader attached to a local Pane. If no cwd can be resolved, then the default_cwd will be used. If default_cwd is not specified, then the home directory of the user will be used.

See default_cwd for an easier to understand visualization.

Passing Environment variables to the spawned program

The set_environment_variables configuration setting can be used to add environment variables to the environment of the spawned program.

The behavior is to take the environment of the wezterm process and then set the specified variables for the spawned process.

config.set_environment_variables = {
  -- This changes the default prompt for cmd.exe to report the
  -- current directory using OSC 7, show the current time and
  -- the current directory colored in the prompt.
  prompt = '$E]7;file://localhost/$P$E\\$E[32m$T$E[0m $E[35m$P$E[36m$_$G$E[0m ',
}

The Launcher Menu

The launcher menu is accessed from the new tab button in the tab bar UI; the + button to the right of the tabs. Left clicking on the button will spawn a new tab, but right clicking on it will open the launcher menu. You may also bind a key to the ShowLauncher or ShowLauncherArgs action to trigger the menu.

The launcher menu by default lists the various multiplexer domains and offers the option of connecting and spawning tabs/windows in those domains.

You can define your own entries using the launch_menu configuration setting. The snippet below adds two new entries to the menu; one that runs the top program to monitor process activity and a second one that explicitly launches the bash shell.

Each entry in launch_menu is an instance of a SpawnCommand object.

config.launch_menu = {
  {
    args = { 'top' },
  },
  {
    -- Optional label to show in the launcher. If omitted, a label
    -- is derived from the `args`
    label = 'Bash',
    -- The argument array to spawn.  If omitted the default program
    -- will be used as described in the documentation above
    args = { 'bash', '-l' },

    -- You can specify an alternative current working directory;
    -- if you don't specify one then a default based on the OSC 7
    -- escape sequence will be used (see the Shell Integration
    -- docs), falling back to the home directory.
    -- cwd = "/some/path"

    -- You can override environment variables just for this command
    -- by setting this here.  It has the same semantics as the main
    -- set_environment_variables configuration option described above
    -- set_environment_variables = { FOO = "bar" },
  },
}

Here's a fancy example that will add some helpful entries to the launcher menu when running on Windows:

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

  -- Find installed visual studio version(s) and add their compilation
  -- environment command prompts to the menu
  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,
}