Hotshell

Interactive single keystroke menus for the shell

Hotshell is a command-line application to efficiently recall and share commands :

Check out the definition and the simulated demo of this menu.

Quick tip : Name your definition file hs.js and hs will pick it up without having to specify a filename.

Content

• Installation
• How to define menus
• JavaScript Runtime
• Configuration
• Examples
• Tips
• Project Motives
• Changelog

Installation

Hotshell is currently supported on Linux, OSX and Windows (10+).

Precompiled packages

• Linux & Windows (WSL) : see releases
• OSX :

brew install julienmoumne/hotshell/hs

Install from source

go get github.com/julienmoumne/hotshell/cmd/hs

How to define menus

Menus are defined using a JavaScript DSL.

Building blocks

Menus are first defined with a top-level menu item

var item = require('hotshell').item

item({desc: 'top level menu'}, function () {
    
})

Command items associate bash commands to hot keys

item({desc: 'top level menu'}, function () {
    
  item({key: 's', cmd: 'sudo service apache2 status'})      
  item({key: 'r', cmd: 'sudo service apache2 restart'})      
  
  // a description can be used to clarify the command intent
  item({key: 'a', desc: 'access logs', cmd: 'less +F /var/log/apache2/access.log'})
  item({key: 'e', desc: 'error logs', cmd: 'less +F /var/log/apache2/error.log'})
})

Submenus and Description items can be used to add structure

item({desc: 'top level menu'}, function () {
    
  item({desc: 'this is a description item, you can use it to describe the menu\n'})
  
  // a submenu to manage apache's daemon
  item({key: 'm', desc: 'apache management'}, function () {
    item({key: 'r', cmd: 'sudo service apache2 restart'})      
    item({key: 'h', cmd: 'sudo service apache2 stop'})
  })
  
  // a submenu to access apache's logs
  item({key: 'l', desc: 'apache logs'}, function () {
    item({key: 'a', desc: 'access', cmd: 'less +F /var/log/apache2/access.log'})
    item({key: 'e', desc: 'error', cmd: 'less +F /var/log/apache2/error.log'})
  })      
})

See a simulated demo and the generated markdown documentation of the resulting menu.

Item properties

item({
  key: 'd', // key used to activate the menu item
  desc: 'directory listing', // description displayed when the item is shown in a menu
  cmd: 'ls -al', // command to execute when the item is activated, only used when not defining a menu (a group of items)
  wd: './subproject', // working directory (relative path) set prior to executing a command or 'exec()'
})

Tips & Examples

Check out tips and fully-featured examples.

JavaScript Runtime

exec

The system can be probed when defining menus using exec()

var exec = require('hotshell').exec

// executes the specified command using `bash -c` and returns the stdout if the command returned a non-zero exit code
stdoutString = exec(commandString)

In case of failure, stderr is displayed in the menu without stopping the interpretation of the DSL.

See some examples.

Underscore.js

Underscore.js is embedded by default in Hotshell.

var _ = require('underscore')

JavaScript Interpreter

The JavaScript is interpreted using Otto, an embeddable JavaScript interpreter. See Otto for available JavaScript functions.

DSL Interpreter

For more information on how the DSL is interpreted see Building Trees using a JavaScript DSL.

Configuration

Keybindings for menu actions can be customized in ~/.hsrc.js :

var settings = require('hotshell-settings')
var keys = settings.keys

settings.set({
  keys: {
    back: keys.Space,
    bash: keys.Tab,
    repeat: keys.Return,
    reload: keys.Backspace
  }
})

Supported keys are listed in Keys.go.

Project Motives

Being more productive using the shell

As developers and system admins we sometimes spend too much time finding and typing commands on the shell.

We rely on a variety of methods to recall commands : search engines, reverse-search-history, aliases, auto-completion, ..

While they are effective, they require superfluous lookups and keystrokes.

Hotshell can be used to define menus containing often and not so often used commands :

// file ~/.hs/hs.js  
item({desc: 'useful system commands'}, function () {
  item({key: 'f', desc: 'find text in files', cmd: 'echo -n "[location] [pattern] "; read l p; grep -rnws $l -e $p'})
  item({key: 'o', desc: 'check local port', cmd: 'echo -n "[port] "; read p; cat < /dev/tcp/127.0.0.1/$p'})
  // other useful commands..
})

Sharing commands

When working in teams we usually go through common steps such as compiling and running tests.

Some of these commands may be available on your IDE, some may not. Team members may not always have the same IDEs.

Most of the time though, IDE task configurations are not committed into the VCS and are therefore not shared.

Hotshell proposes both a way to :

• spread command-line skills in teams
• produce executable documentation

As an example, checkout Hotshell's hotshell