Skip to main content
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