Toolkit for building a bash-like shell in the browser, including full readline support

Project maintained by sdether Hosted on GitHub Pages — Theme by mattgraham

josh.js 0.2

Javascript Online SHell provides a toolkit for building bash-like command line consoles for web pages. It consists of the following components:

Live Demo

Drag bottom of shell to change size.
Type help or hit TAB for a list of commands.

Annotated source of demo




josh.js is licensed under the Apache 2.0 License



Until documentation is written, refer to index.html and the annotated version of example.js for a sample implementation of a shell with path completion.


josh is built from 5 components and can be used in part or in full.


readline.js has no dependencies on any outside libraries, although it requires either history.js and killring.js or objects implementing the same calls.

It implements key trapping to bring GNU Readline like line editing to the browser. It can be used by itself to bring readline support to custom data entry fields or in conjunction with shell.js to create a full console.

Line Editing

In the below C-x refers to the Ctrl-x keystroke, while M-x refers to the Meta-x keystroke which is mapped to Alt, and Left Windows.

C-b or Left Arrow
Move back one character
M-b or Right Arrow
Move back one word
Move forward one character
Move forward one word
C-a or Home
Move to the beginning of the line
C-e or End
Move to the end of the line

Delete one character back
C-d or Delete
Delete character under cursor
Kill (i.e. put in kill ring) text to the end of the line
Kill one word back
Kill word under cursor
Yank (i.e. pull from kill ring) the most recently killed text
Rotate to the next item in killring and yank it. Must be preceded by yank

Reverse search through history
C-p or Up Arrow
Previous entry in history
C-n or Down Arrow
Next entry in history
Page Up
Top of history
Page Down
Bottom of history

refresh line (clear screen in shell)
Invoke completion handler for text under cursor
Esc in reverse search
Cancel search
call onCancel handler
C-d on empty line
call onCancel handler

More readline.js docs


shell.js has external dependencies of jQuery, Underscore and internal dependencies of readline.js and history.js.

It provides a simple console UI, using a panel for the console viewport and an auto-scrolling view inside the panel. It uses Underscore templates for generating the view html, although any template generator can be substituted as long as it can be expressed in the form of a function that takes a JSON object of arguments and returns an html string.

It also implements command handling so that new commands can be added by name with execution and completion handlers. Out of the box, shell.js provides the following commands:

More shell.js docs


pathhandler.js is a mix in to easily add the cd, ls and pwd commands as well as path completion. It has Underscore as its dependency for templating, however since all templates it uses are exposed, they could easily be replaced with a different function that accepts an argument object returns html.

By implementing the functions getNode and getChildNodes, this library adds path traversal, discovery and completion just like a bash shell.

More pathhandler.js docs


history.js implements a localStorage back command history storage that persists over page changes and reloads. It is used by the shell.js history command to list all executed commands, and by readline.js for up/down arrow and reverse search capabilities.


killing.js implements the kill and yank behavior as well as state tracking, i.e. multiple consecutive kills are combined as a single kill and killring rotation tracks the previous yank, so that the readline.js can remove the previous yank and replace it with the rotated text.