Building command line tools (CLI) in Node.js JavaScript from scratch

Written by NickWal

Originally developed from the JavaScript engine you find in browsers such as google chrome, Nodejs is a JavaScript engine for running scripts in a variety of other environments. Given the large amount of libraries developed for JavaScript it provides a very productive environment for writing quite sophisticated command line tools. The command line tools can be installed globally on your computer, and if carefully written will work exactly the same on Windows as on Linux.

There are a large number of tutorials on the Internet showing you how to install NodeJS, and principles of JavaScript programming, as well as several well equipped editors with syntax highlighting and code completion, so I won’t dwell on those points here, rather this tutorial will concern itself with the unique needs of developing command line tools, such as parsing the command line, saving settings, installation and so on.

Getting Started

The first step is to create your project. From the command line type the following:

mkdir myclitools
cd myclitools
npm init

And answer the questions:

name: (myclitools) hello
version: (1.0.0) 0.0.1
description: Example to demonstrate creating a command line tool
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)
About to write to C:\src\myclitools\package.json:

{
"name": "hello",
"version": "0.0.1",
"description": "Example to demonstrate creating a command line tool",
"main": "index.js",
"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "ISC"
}


Is this ok? (yes)

Then install a helper which takes care of a number of features that all CLI tools need to have

npm install --save woofwoof

WoofWoof is a fork I created from the popular meow tool which is also a CLI tool helper which uses minimist for parsing arguments. I found that as I developed CLI tools I needed the additional functionality of being able to save settings, and override them in the CLI. For example I might have a different default output directory on different machines. WoofWoof uses nconf instead of minimist to parse the command line arguments, however in addition it also has functionality for saving settings, and reading configuration from environment variables.

Next - fire up your favourite text editor and edit the file package.json. Look for the line that begins with author and insert the following:

 "bin": "./index.js",

This is a reference to which script will be invoked when the command is executed from the command line.

Sample script

Update the index.js file to read as follows:

#!/usr/bin/env node

/*jshint node:true */
/*jshint esversion:6 */
'use strict';


const woofwoof = require('woofwoof');

const cli = woofwoof(`
    Usage
    $ hello <input>

    Options
    --name, -n  Who should I greet

`, {
    alias: {
        n: 'name'
    }, default: {
        name: "world"
    }
});

function hello(input,flags) {
console.log("hello "+flags.name);
}


hello(cli.input[0], cli.flags);

This file demonstrates the use of woofwoof for default values and saving settings.

Local installation

To install the application

npm install -g      

You will now have an example application installed in your computer called “hello”. You can now try some of the following commands:

C:\src\myclitools>hello
hello world

C:\src\myclitools>hello -n Jim
hello Jim

C:\src\myclitools>hello -n Jim --save-settings
Saving Settings

C:\src\myclitools>hello
hello Jim

You can also check out the file in your home directory ~/.hello/settings.json. You’ll see this is a simple JSON file containing your settings.

Good luck!