wezterm connect

Connect to a WezTerm multiplexer domain

The connect command connects to a named multiplexer domain configured in your WezTerm configuration file.

Synopsis

wezterm connect [OPTIONS] <DOMAIN_NAME> [PROG]...

Description

Connects to a multiplexer domain that you’ve defined in your WezTerm configuration. This allows you to attach to remote or local multiplexer sessions and work with persistent terminal sessions.

Arguments

DOMAIN_NAME · string · required

Name of the multiplexer domain section from the configuration to which you’d like to connect.

This must match a domain name defined in your wezterm.lua configuration file.

Example:

wezterm connect my_remote_server

PROG · string[]

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

Example:

wezterm connect my_domain -- bash -l

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

Options

--new-tab · flag

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

--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 connect my_domain --workspace production

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

Configuration Example

Before using wezterm connect, you need to define multiplexer domains in your wezterm.lua:

local wezterm = require 'wezterm'

return {
  unix_domains = {
    {
      name = 'unix',
      -- Connect automatically
      connect_automatically = true,
    },
  },
  ssh_domains = {
    {
      name = 'my_remote_server',
      remote_address = 'server.example.com',
      username = 'myuser',
    },
  },
}

Examples

Connect to a Unix domain

wezterm connect unix

Connect to an SSH domain

wezterm connect my_remote_server

Connect and spawn in a new tab

wezterm connect my_domain --new-tab

Connect with a specific workspace

wezterm connect my_domain --workspace dev

Connect and run a specific program

wezterm connect my_domain -- tmux attach

Related

• wezterm start - Start a new terminal session
• wezterm ssh - Connect via SSH without pre-configured domains