zsh-ssh

Better host completion for ssh in Zsh.

• zsh-ssh
  • Installation
    • Zinit
    • Antigen
    • Oh My Zsh
    • Sheldon
    • Manual (Git Clone)
  • 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

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

2. Add the plugin to the list of plugins for Oh My Zsh to load (inside ~/.zshrc):

   plugins=(zsh-ssh $plugins)

3. Start a new terminal session.

Sheldon

1. Add this config to ~/.config/sheldon/plugins.toml

   [plugins.zsh-ssh]
   github = 'sunlei/zsh-ssh'

2. Run sheldon lock to install the plugin.

3. Start a new terminal session.

Manual (Git Clone)

1. Clone this repository somewhere on your machine. For example: ~/.zsh/zsh-ssh.

   git clone https://github.com/sunlei/zsh-ssh ~/.zsh/zsh-ssh

2. Add the following to your .zshrc:

   source ~/.zsh/zsh-ssh/zsh-ssh.zsh

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