Gem Version Dependency Status Code Climate Coverage Status Build Status 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 usage

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.
  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 -> [email protected]")
    • 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 ("[email protected]#$1.example.org")
    • This will be evaluated using Ruby's string interpolation, so you can use "#var", "#$1", "#function()", etc.
  3. 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 'fish.alpha.cat'


  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 [email protected]
PTY allocation request failed on channel 0
Hi akerl! You've successfully authenticated, but GitHub does not provide shell access.
Connection to github.com closed.


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.