SSH helper
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin fix cops Sep 16, 2017
spec fix cops Sep 16, 2017
.circle-ruby update ruby Feb 12, 2019
.gitignore fix tests now Feb 11, 2014
.rspec theft from basiccache; fixes #8, fixes #13 Nov 23, 2013
.travis.yml switch to travis Aug 29, 2018 add HSS_COMMAND support, release v1.0.1 May 16, 2015
Gemfile theft from basiccache; fixes #8, fixes #13 Nov 23, 2013
LICENSE switch readme badge to travisci Aug 28, 2018
Rakefile bump rubocop dep Jun 2, 2014
hss.gemspec Updated version of rubocop to 0.64.0 Feb 11, 2019


Gem Version Build Status Coverage Status Code Quality MIT Licensed

SSH helper that uses regex and fancy expansion to dynamically manage SSH shortcuts


gem install hss
ln -s /path/to/your/config.yml ~/.hss.yml

SCP configuration

This script can be used by SCP and other things that use SSH as a transport. To use it with SCP, just specify hss for the -S flag:

scp -S hss host:files/ other_host:location/

To use it with rsync, use the -e flag:

rsync -e hss files/ host:location/

You can alias this for the greater good:

alias pcs='scp -S hss'
alias cnysr='rsync -e hss'

Caveat: Because of how hss processes hosts, it will only operate on the first host-like thing in your command. As such, using scp to copy a local file to an hss'd host will work, as will the inverse, and copying a file from an hss'd host to a normal host works, but not the inverse.


  1. You can put your configuration in ~/.hss.yml or another file specified by the "HSS_CONFIG" environment variable. You can refer to multiple config files in "HSS_CONFIG" by separating them with colons and the configs will be merged (HSS_CONFIG=$HOME/.hss-shared.yml:$HOME/.hss-mine.yml).
  2. The only required configuration section is "patterns", which contains an array of hashes with the following attributes:
  • note: Name of this pattern ("my servers")
  • example: Shows how this is used ("jimbo ->")
  • short: Regex for shortcut ("^(jimbo|bob|chuck)$")
    • Use matching to collect things you want to use in the expanded form
  • long: Expanded form of this shortcut ("root@#$")
    • This will be evaluated using Ruby's string interpolation, so you can use "#{var}", "#$1", "#{function()}", etc.
  1. Helpers are available for use in long forms
  • expand(x): Uses the "expansions" section of the config. Format for this section is a hash of lists, as such:
        - short_form1
        - short_form2
        - shrtfrm3
  • shortcut(x): Uses the "shortcuts" section of the config. Format for this section is a hash of strings, as such
    short1: expand to this
    other_short: 'expand to something else!'
  • command(x): Runs the given string as a command and uses the output for the expanded form
  • default(x, y): If x is not nil, uses x. If it's nil, use y
  • external(source, key): Loads source as a YAML file and looks for the given key. The YAML should be made of hashes (you can nest them) and the key should be dot-separated:
    color: blue # accessible with key = 'fish.color'
        dog: sparky
        cat: grouchy # accessible with key ''


  1. Run hss help for a list of available commands
  2. Run hss $command to do that thing

Falling back to another command

If you define the environment variable "HSS_PASS", hss will fall back to that command if it fails to find a match:

# export HSS_PASS='ssh'

# hss
PTY allocation request failed on channel 0
Hi akerl! You've successfully authenticated, but GitHub does not provide shell access.
Connection to closed.

Changing the default command

By default, hss prepends "ssh " to the long command from your configuration file. If you're using something different (like mosh), you can set HSS_COMMAND in your environment to override that.


If you want hss to print the command it would have run rather than executing it, you just need to set the HSS_DEBUG environment variable to something:

export HSS_DEBUG=foo
hss bar # will print rather than exec


hss is released under the MIT License. See the bundled LICENSE file for details.