wezterm start

Start the WezTerm GUI, optionally running an alternative program

The start command launches the WezTerm GUI with optional customization of the initial program, working directory, window position, and more.

Synopsis

wezterm start [OPTIONS] [PROG]...

Description

Starts the WezTerm graphical user interface. By default, it will spawn your configured shell, but you can override this behavior to run a specific program. The command supports both launching new WezTerm instances and spawning into existing ones.

Arguments

PROG · string[]

Instead of executing your shell, run PROG. The program and its arguments should be specified after --.

Example:

wezterm start -- bash -l

This will spawn bash as if it were a login shell.

Alias: This can also be specified with -e for compatibility with other terminal emulators.

Options

--no-auto-connect · flag

If true, do not connect to domains marked as connect_automatically in your wezterm configuration file.

--always-new-process · flag

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.

Useful for scripting scenarios where you need to wait for the terminal session to complete.

--new-tab · flag

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

Note: Conflicts with --always-new-process

--cwd · path

Specify the current working directory for the initially spawned program.

Example:

wezterm start --cwd /home/user/projects

--class · string

Override the default windowing system class. The default is org.wezfurlong.wezterm.

• Under X11 and Windows: changes the window class
• Under Wayland: 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 · string

Override the default workspace with the provided name. The default is "default".

Example:

wezterm start --workspace project1

--position · string

Override the position for the initial window launched by this process.

Format options:

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

Wayland does not allow applications to control window positioning.

--domain · string

Name of the multiplexer domain section from the configuration to which you’d like to connect. If omitted, the default domain will be used.

Example:

wezterm start --domain my_remote_domain

--attach · flag

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.

Note: Requires --domain to be specified

Examples

Start with a specific program

wezterm start -- htop

Start in a specific directory

wezterm start --cwd ~/projects/myapp

Start in a new tab of existing window

wezterm start --new-tab

Start with a custom workspace

wezterm start --workspace development -- nvim

Start at a specific window position

wezterm start --position main:0,0

Connect to a multiplexer domain

wezterm start --domain unix --attach

Compatibility with other terminals

The -e flag is supported for compatibility:

wezterm start -e bash -l

However, using -- is recommended:

wezterm start -- bash -l