nodejs module that helps expose unix commands as web services
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Unix command line utilities as web services

Build Status


This module provides functions that allow the exposure of any unix command utility to node.js mapping the commands stdin and stdout to the webserver in out and the url's path to the uitilities arguments. There are two functions webCommand and getCommandList.

#Description To use this module, you need to first

var webcommand = require('webcommand')([commandList]);

The webcommand creates spawns a separate process, pipe-ing the input and output streams as needed. It also accepts a ctrlStream to emit errors and signal the end of the command. Command is sth that can be exec-ed so it has to be found in the current process's path Arguments is the list of arguments that we are passing to the process.

webcommand.webCommand(command,arguments, inStream, outStream, ctrlStream);

To get the list of allowed commands for a CommandServer.


The 'normal' use case for this library is to expose the power of the unix command utilities within a more restricted enviorment, for example the browser. For example you can easily create an awk javascript function (replace sort above with awk..). Note that while these unix facilities are obtaining significant user access (even readonly) to the server, the server would probably be a rooted slug - e.g. a heroku app - whose disk is containing no user information besides the code it serves.

#Example with express In this example a post of a form in index.html will call sort and stream the results back to browser.

var express = require('express'),
    webCommand = require('../')(),
    stream = require('event-stream');

var port = process.env.PORT || 8000;
var app = express();

app.get('/getCommands', function(req,res) {

app.get('/', function(req,res) {
    });'/*', function(req,res){
    var cmd = req.path.replace('/','');
        args = [].concat(req.query.args);
        cStream= stream.through();
    if (req.query.args === '') args = null;

    cStream.on('error', function(err) {
    webCommand.webCommand(cmd,args, req, res, cStream);


Note that the only reliable way to detect the end of the webcommand is via the cStream's end. (cStream.on('end')).


To run locally the example:

> hub clone ogt/webcommand && cd webcommand
> npm install
> make test
> node example/example.js&
> open localhost:8000/getCommands &
> open localhost:8000 

You can test the default command (sort) or replace any command that is in your path. Remember that if if you are to use a command that doesn't need stdin you will need to clear the input textarea - otherwise you will get a pipe error.