One of the lesser known features of Node is the ability to write command line utilities. This article aims to document the basics on how to go about creating and testing your command line utility.

Setting up your project

Starting with a blank folder, cd into it and then run:

npm init

Fill in all the details and when it finishes you should be left with a basic package.json file. You will then need to add a few extra bits to the file. Add the following lines to your file:

preferGlobal : true,
bin : {
	"yourcommandname" : './bin/yourcommandname'
}

The preferGlobal pretty much does what it says and springs up a warning if somebody tries to install it without the -g. The bin section defines which command runs what files.

Once that’s in there create a bin directory and a file called yourcommandname. The skeleton of the file should look something like this:

#!/usr/bin/env node

var applogic = require('../lib/applogic');

process.title = 'My App';

appLogic.runSomething("stuff", function(error, result) {
	
	if (error) {
		console.log("error");
	} else {
		console.log("done");
	}
	

	process.exit(error ? 1 : 0);
});

The top line is to get the script to be executed by node, from then on it’s just standard stuff. Whilst it isn’t essential it’s still worth moving your application logic to a lib folder so that you can unit test it more easily. When you are done you can return a 1 or a 0 to specify pass or fail.

Parameter Passing

You can also pass parameters into the script. To grab the variables within your script you can use process.argv. This holds an array of all the space seperated parameters input into your script. So, the command:

command these are my params=yesh

will return an argv array with 4 items: ['these', 'are', 'my', 'params=yesh']. There are also some libraries around that make it easier if that’s what your after. Take a look at Optomist.

Console Colo[u]r

Everybody loves colours right? The easiest way to do that is to use the colors module. To install:

npm install colors

Then to output colors to the console just specify the color in the log method

console.log("This is red".red);

It also allows you to define chain modifications with commands like:

console.log("This is bold and colourful".bold.rainbow);

That’s the colours sorted. Now your probably going to want to run it.

Testing

Whilst your unit tests will test your application logic you are probably going to want to run your task from the command line just to check it end to end before you publish it to npm. You can simulate a -g installation using npm. Within the root directory of your project run:

npm link

Depending on platform i.e. mac, linux you will probaly have to prefix that with a sudo. This creates a symbolic link to your project from the global package location. You should then be able to run your command anywhere.

You can then remove the link once you have finished by running unlink from your project folder:

npm unlink

There you have it. If you use this and make loads of money, make sure you give me some.