wezterm ssh

Establish an SSH session with WezTerm

The ssh command establishes an SSH connection to a remote system using WezTerm’s built-in SSH client.

Synopsis

wezterm ssh [OPTIONS] <USER_AT_HOST_AND_PORT> [PROG]...

Description

Establishes an SSH session to a remote system. WezTerm includes a built-in SSH client that can parse SSH configuration files and provides a native terminal experience with full feature support.

Arguments

USER_AT_HOST_AND_PORT · string · required

Specifies the remote system using the form: [username@]host[:port]

• If username@ is omitted, your local $USER is used
• If :port is omitted, the standard SSH port (22) is used

Examples:

wezterm ssh [e-mail]
wezterm ssh example.com:2222
wezterm ssh [e-mail]:2222
wezterm ssh example.com

PROG · string[]

Instead of executing your shell, run PROG on the remote system.

Example:

wezterm ssh user@host -- bash -l

This will spawn bash as if it were a login shell on the remote system.

Options

-o, --ssh-option · name=value

Override specific SSH configuration options. Can be specified multiple times.

WezTerm’s SSH client can parse some (but not all!) options from your ~/.ssh/config and /etc/ssh/ssh_config files. This command line switch allows you to override or otherwise specify ssh_config style options.

Example:

wezterm ssh -oIdentityFile=/secret/id_ed25519 some-host
wezterm ssh -oPort=2222 -oUser=admin example.com

-v · flag

Enable verbose SSH protocol tracing.

The trace information is printed to the stderr stream of the process. Useful for debugging connection issues.

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

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

Examples

Basic SSH connection

wezterm ssh [e-mail]

Connect to non-standard port

wezterm ssh [e-mail]:2222

Use specific identity file

wezterm ssh -oIdentityFile=~/.ssh/id_custom [e-mail]

Multiple SSH options

wezterm ssh -oPort=2222 -oUser=admin -oIdentityFile=/path/to/key example.com

Enable verbose debugging

wezterm ssh -v [e-mail]

Run a specific command

wezterm ssh [e-mail] -- htop

Open at specific window position

wezterm ssh --position main:0,0 [e-mail]

SSH Configuration

WezTerm respects your SSH configuration files:

• ~/.ssh/config
• /etc/ssh/ssh_config

You can define host aliases and settings in these files, and WezTerm will use them:

Host myserver
    HostName example.com
    User myuser
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

Then simply:

wezterm ssh myserver

Features

• Built-in SSH client (no external SSH binary required)
• Supports SSH agent forwarding
• Respects SSH config files
• Full terminal feature support (colors, mouse, clipboard, etc.)
• Integrated with WezTerm’s multiplexer capabilities

Related

• wezterm connect - Connect to pre-configured multiplexer domains
• wezterm start - Start a local terminal session