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

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

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

  **Example:**

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

## Options

<ParamField path="--no-auto-connect" type="flag">
  If true, do not connect to domains marked as `connect_automatically` in your wezterm configuration file.
</ParamField>

<ParamField path="--always-new-process" type="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.
</ParamField>

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

  **Note:** Conflicts with `--always-new-process`
</ParamField>

<ParamField path="--cwd" type="path">
  Specify the current working directory for the initially spawned program.

  **Example:**

  ```bash theme={null}
  wezterm start --cwd /home/user/projects
  ```
</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 start --workspace project1
  ```
</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

  <Note>
    Wayland does not allow applications to control window positioning.
  </Note>
</ParamField>

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

  ```bash theme={null}
  wezterm start --domain my_remote_domain
  ```
</ParamField>

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

## Examples

### Start with a specific program

```bash theme={null}
wezterm start -- htop
```

### Start in a specific directory

```bash theme={null}
wezterm start --cwd ~/projects/myapp
```

### Start in a new tab of existing window

```bash theme={null}
wezterm start --new-tab
```

### Start with a custom workspace

```bash theme={null}
wezterm start --workspace development -- nvim
```

### Start at a specific window position

```bash theme={null}
wezterm start --position main:0,0
```

### Connect to a multiplexer domain

```bash theme={null}
wezterm start --domain unix --attach
```

### Compatibility with other terminals

The `-e` flag is supported for compatibility:

```bash theme={null}
wezterm start -e bash -l
```

However, using `--` is recommended:

```bash theme={null}
wezterm start -- bash -l
```