> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# wezterm connect

> Connect to a WezTerm multiplexer domain

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

## Synopsis

```bash theme={null}
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

<ParamField path="DOMAIN_NAME" type="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:**

  ```bash theme={null}
  wezterm connect my_remote_server
  ```
</ParamField>

<ParamField path="PROG" type="string[]">
  Instead of executing your shell, run PROG. The program and its arguments should be specified after the domain name.

  **Example:**

  ```bash theme={null}
  wezterm connect my_domain -- bash -l
  ```

  This will spawn bash as if it were a login shell.
</ParamField>

## Options

<ParamField path="--new-tab" type="flag">
  When spawning into an existing GUI instance, spawn a new tab into the active window rather than spawn a new window.
</ParamField>

<ParamField path="--class" type="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.
</ParamField>

<ParamField path="--workspace" type="string">
  Override the default workspace with the provided name. The default is `"default"`.

  **Example:**

  ```bash theme={null}
  wezterm connect my_domain --workspace production
  ```
</ParamField>

<ParamField path="--position" type="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
</ParamField>

## Configuration Example

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

```lua theme={null}
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

```bash theme={null}
wezterm connect unix
```

### Connect to an SSH domain

```bash theme={null}
wezterm connect my_remote_server
```

### Connect and spawn in a new tab

```bash theme={null}
wezterm connect my_domain --new-tab
```

### Connect with a specific workspace

```bash theme={null}
wezterm connect my_domain --workspace dev
```

### Connect and run a specific program

```bash theme={null}
wezterm connect my_domain -- tmux attach
```

## Related

* [wezterm start](/cli/start) - Start a new terminal session
* [wezterm ssh](/cli/ssh) - Connect via SSH without pre-configured domains