zsh-ssh

May 29, 2026 · View on GitHub

Better host completion for ssh in Zsh.

zsh-ssh
- Installation
- Usage
  - Configuration
  - SSH Config Example

Installation

Make sure you have fzf installed. The column command is optional and only improves table/preview alignment; the plugin falls back to plain formatting when it is unavailable.

Zinit

zinit light sunlei/zsh-ssh

Antigen

antigen bundle sunlei/zsh-ssh

Oh My Zsh

Clone this repository into $ZSH_CUSTOM/plugins (by default ~/.oh-my-zsh/custom/plugins)

git clone https://github.com/sunlei/zsh-ssh ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-ssh

Add the plugin to the list of plugins for Oh My Zsh to load (inside ~/.zshrc):
```
plugins=(zsh-ssh $plugins)
```
Start a new terminal session.

Sheldon

Add this config to ~/.config/sheldon/plugins.toml
```
[plugins.zsh-ssh]
github = 'sunlei/zsh-ssh'
```
Run sheldon lock to install the plugin.
Start a new terminal session.

Manual (Git Clone)

Clone this repository somewhere on your machine. For example: ~/.zsh/zsh-ssh.
```
git clone https://github.com/sunlei/zsh-ssh ~/.zsh/zsh-ssh
```
Add the following to your .zshrc:
```
source ~/.zsh/zsh-ssh/zsh-ssh.zsh
```
Start a new terminal session.

Usage

Just press Tab after ssh command as usual.

Configuration

Known hosts are not included by default. To include plain hostnames from ~/.ssh/known_hosts, enable it explicitly:

export ZSH_SSH_INCLUDE_KNOWN_HOSTS=1

By default, the plugin reads $HOME/.ssh/known_hosts. To use another file:

export ZSH_SSH_KNOWN_HOSTS_FILE="$HOME/.ssh/known_hosts"

Hashed known_hosts entries cannot be converted back to hostnames and are skipped.

SSH Config Example

You can use #_Desc to set description.

~/.ssh/config

Host Bastion-Host
    Hostname 1.1.1.1
    User sunlei

Host Development-Host
    Hostname 2.2.2.2
    IdentityFile ~/.ssh/development-host
    #_Desc For Development

You can use OpenSSH Tag to group hosts in the list:

Host Work-Bastion
    Hostname bastion.example.com
    User deploy
    Tag work
    #_Desc Bastion host

Host Home-NAS
    Hostname 192.168.1.20
    User root
    Tag personal
    #_Desc NAS

When any host has a Tag, zsh-ssh shows a Tag column. You can type work in fzf to search for tagged hosts, or use ssh tag:work<Tab> to filter the completion list by tag before fzf opens.

Include files are also supported. For example, your main config can include separate files:

~/.ssh/config

Include ~/.ssh/config.d/company.ssh_config
Include ~/.ssh/config.d/home.ssh_config
Include ~/.ssh/config.d/work.ssh_config

# OR

Include ~/.ssh/config.d/*.ssh_config