DOCSEARCHbyAlgolia
Submit Docs

zsh-ssh

repository·master·Indexed 42 days ago

https://github.com/sunlei/zsh-ssh

A Zsh plugin that provides enhanced host completion for the ssh command using fzf. It allows users to view descriptions, tags, and known_hosts entries during the completion process, with support for filtering by tags and custom metadata in the SSH config file.

Tokens
991
Snippets
4
Records
4
Agent score
3%

What's inside zsh-ssh

  1. Add descriptions and tags to SSH config

    master

    You can enhance the zsh-ssh completion interface by adding metadata to your ~/.ssh/config file:

    1. Descriptions: Use #_Desc followed by text to provide a human-readable description for a host. This will appear in the completion list.
    2. Tags: Use the OpenSSH Tag directive to group hosts. When any host in your config has a Tag, zsh-ssh displays a Tag column in the completion UI.

    Searching/Filtering by Tag:

    • You can type the tag name directly into the fzf prompt to filter hosts.
    • You can use the syntax ssh tag:<tag_name><Tab> to filter the completion list before the fzf interface opens.
    # ~/.ssh/config

Host Bastion-Host
    Hostname 1.1.1.1
    User sunlei
    #_Desc For Bastion access

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

  2. Install zsh-ssh via plugin managers

    master

    Before installing, ensure you have fzf installed. The column command is optional and used for improved table/preview alignment; the plugin will fall back to plain formatting if it is missing.

    Choose the command corresponding to your Zsh plugin manager:

    • Zinit: Use zinit light sunlei/zsh-ssh.
    • Antigen: Use antigen bundle sunlei/zsh-ssh.
    • Oh My Zsh: Clone the repo into $ZSH_CUSTOM/plugins and add zsh-ssh to your plugins=(...) array in ~/.zshrc.
    • Sheldon: Add the plugin to ~/.config/sheldon/plugins.toml and run sheldon lock.
    • Manual: Clone the repository and source the zsh-ssh.zsh file in your ~/.zshrc.
    ### Zinit
```shell
zinit light sunlei/zsh-ssh

    Antigen

    antigen bundle sunlei/zsh-ssh

    Oh My Zsh

    git clone https://github.com/sunlei/zsh-ssh ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-ssh
# Then in ~/.zshrc:
plugins=(zsh-ssh $plugins)

    Sheldon

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

    Manual (Git Clone)

    git clone https://github.com/sunlei/zsh-ssh ~/.zsh/zsh-ssh
# Then in ~/.zshrc:
source ~/.zsh/zsh-ssh/zsh-ssh.zsh

  3. Configure known_hosts inclusion and file path

    master

    By default, zsh-ssh does not include hosts from your known_hosts file. You can enable this and specify a custom file path using environment variables in your .zshrc.

    Note: Hashed entries in known_hosts cannot be converted back to hostnames and will be skipped by the plugin.

    # Enable inclusion of plain hostnames from known_hosts
export ZSH_SSH_INCLUDE_KNOWN_HOSTS=1

# Specify a custom known_hosts file (defaults to $HOME/.ssh/known_hosts)
export ZSH_SSH_KNOWN_HOSTS_FILE="$HOME/.ssh/custom_known_hosts"

  4. Use zsh-ssh for host completion

    master

    Once installed, the plugin enhances the standard ssh command completion. Simply type ssh followed by a space and press <Tab> to trigger the enhanced host completion interface (powered by fzf).

    ssh <Tab>