❯❯ ssh-host

zsh plugin that cuts ssh and scp boilerplate

Table of Contents

• Key Features
• Requirements
• Getting Started
• Key Bindings
• Tips
• Troubleshooting

Key Features

Interactive Host Selection

Browse hosts from .ssh/config with fuzzy search and live preview of connection details, port, key, and descriptions. Filter and navigate with keyboard.

Quick Host Setup

Press Ctrl+N to add new hosts through guided setup. Behind the scenes the plugin:

• Generates an ed25519/RSA-4096 key (or skips key generation for password-based auth)
• Backs up existing SSH config and keys before any changes
• Appends the host to a ssh config file via Include directive, leaving your main config untouched
• Adds key to SSH agent
• Deploys the public key to the server via ssh-copy-id

SCP Support

Upload files/directories with Ctrl+U, download with Ctrl+D. Auto-detects recursive transfers for directories.

Pin

Press Ctrl+P to pin frequently-used hosts to the top of your list. Quick access to servers or most used environments.

Custom Descriptions

Press Ctrl+E to add descriptions to hosts. Document server purpose, environment (prod/staging/dev), or notes.

Requirements

• zsh >= 5.0
• fzf - Fuzzy finder for interactive selection

Getting Started

1. Install fzf

2. Install ssh-host:

   Zinit / Antigen / Znap

   Add to your ~/.zshrc:

   zinit load "obolientsev/ssh-host"
   # or
   antigen bundle obolientsev/ssh-host
   # or
   znap source "obolientsev/ssh-host"

   or

   Oh My Zsh

   1. Clone the repository:

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

   2. Add to your plugins list in ~/.zshrc:

   plugins=(ssh-host $plugins)

   3. Restart your shell:

   source ~/.zshrc

3. Launch the plugin:

   ssh-host

4. Follow the instructions to add your first host.

Key Bindings

Key	Action
↑/↓	Navigate hosts
Enter	Connect to selected host
Ctrl-N	Add new host
Ctrl-E	Edit selected host description
Ctrl-P	Toggle pin status of selected host
Ctrl-U	Upload file to selected host
Ctrl-D	Download file from selected host
Esc	Quit

Tips

Adding a new SSH key to your GitHub account

To configure your account on GitHub.com you need add an SSH key to your GitHub account. To generate new SSH key and configure it correctly follow these steps:

1. Open ssh-host → press Ctrl-N
2. Fill in the wizard:
   • Alias: github
   • Hostname: github.com
   • User: git
   • Port: 22
   • Key type: ed25519
3. Confirm setup
4. Copy Public key from response:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIgiKN9FQcPgCUuA81PSn28ThZQANY0v4pvMTfjZo8Ka github@demo

5. Paste into GitHub Settings → SSH keys

For more details GitHub docs

Multiple GitHub accounts (personal + work)

Useful if you contribute to repos with a personal account but push to work repos under a different account. SSH doesn't support multiple identities for the same hostname out of the box — aliases solve this.

1. Add SSH key (see tip above) for personal account with alias github-personal
2. Add SSH key (see tip above) for work account with alias github-work
3. Copy each pubkey to the corresponding GitHub account's SSH keys
4. Use the alias in git remotes instead of github.com:

   # in work project
   git remote set-url origin github-work:org/work_repo.git
   # in personal project
   git remote set-url origin github-personal:username/repo.git

Multi-alias Host entries

If you use multi-alias Host blocks in your SSH config, the plugin shows each alias as a separate entry:

Host production prod p
    HostName example.com
    User ubuntu

All three — production, prod, p — appear in the list by default.

To show only the first alias per block, add to your ~/.zshrc:

export SSH_HOST_SHOW_ALL_SUB_ALIAS=false

Troubleshooting

Too many authentication failures

Issue: SSH server rejects connection after trying too many keys. Happens when ssh-agent has multiple keys loaded and SSH tries them all before the correct one, exceeding server's MaxAuthTries limit (typically 6 attempts).

Fix: Add IdentitiesOnly yes to force SSH to use only specified keys, not all agent keys.

Update config:

Host problematic-host
    HostName example.com
    User myuser
    IdentityFile ...
    IdentitiesOnly yes  # Add this line

Prevent globally: Add to ~/.ssh/config top:

Host *
    IdentitiesOnly yes

---

Note

This plugin manages SSH configurations in a separate file to avoid conflicts with your existing setup. All generated keys are stored in ~/.ssh/ssh_host/keys/.