Build a JavaScript Command Line Interface (CLI) with Node.js

As great as Node.js is for "traditional" web applications, its potential uses are far broader. Microservices, REST APIs, tooling, working with the Internet of Things and even desktop applications—it's got your back.

Another area where Node.js is really useful is for building command-line applications—and that's what we're going to be doing today. We're going to start by looking at a number of third-party packages designed to help work with the command-line, then build a real-world example from scratch.

What we're going to build is a tool for initializing a Git repository. Sure, it'll run git init under the hood, but it'll do more than just that. It will also create a remote repository on Github right from the command line, allow the user to interactively create a .gitignore file and finally perform an initial commit and push.

As ever, the code accompanying this tutorial can be found on our GitHub repo.

Why Build a Command-line Tool with Node.js?

Before we dive in and start building, it's worth looking at why we might choose Node.js to build a command-line application.

The most obvious advantage is that if you're reading this, you're probably already familiar with it—and indeed, with JavaScript.

Another key advantage, as we'll see as we go along, is that the strong Node.js ecosystem means that among the hundreds of thousands of packages available for all manner of purposes, there are a number which are specifically designed to help build powerful command-line tools.

Finally, we can use npm to manage any dependencies, rather than have to worry about OS-specific package managers such as Aptitude, Yum or Homebrew.

That said, that's not necessarily true, in that your command-line tool may have other external dependencies.

What We're Going to Build—Introducing ginit

For this tutorial, We're going to create a command-line utility which I'm calling ginit. It's git init, but on steroids.

You're probably wondering what on earth that means.

As you no doubt already know, git init initializes a git repository in the current folder. However, that's usually only one of a number of repetitive steps involved in the process of hooking up a new or existing project to Git. For example, as part of a typical workflow, you might well:

1. Initialise the local repository by running git init
2. Create a remote repository, for example on Github or Bitbucket; typically by leaving the command-line and firing up a web browser
3. Add the remote
4. Create a .gitignore file
5. Add your project files
6. Commit the initial set of files
7. Push up to the remote repository

There are often more steps involved, but we'll stick to those for the purposes of our app. Nevertheless, these steps are pretty repetitive. Wouldn't it be better if we could do all this from the command-line, with no copying-and-pasting of Git URLs and such-like?

So what ginit will do is create a Git repository in the current folder, create a remote repository—we'll be using Github for this—and then add it as a remote. Then it will provide a simple interactive "wizard" for creating a .gitignore file, add the contents of the folder and push it up to the remote repository. It might not save you hours, but it'll remove some of the initial friction when starting a new project.

With that in mind, let's get started.

The Application Dependencies

One thing is for certain—in terms of appearence, the console will never have the sophistication of a graphical user interface. Nevertheless, that doesn't mean it has to be plain, ugly, monochrome text. You might be surprised by just how much you can do visually, while at the same time keeping it functional. We'll be looking at a couple of libraries for enhancing the display: chalk for colorizing the output and clui to add some additional visual components. Just for fun, we'll use figlet to create a fancy ASCII-based banner and we'll also use clear to clear the console.

In terms of input and output, the low-level Readline Node.js module could be used to prompt the user and request input, and in simple cases is more than adequate. But we're going to take advantage of a third-party package which adds a greater degree of sophistication—Inquirer. As well as providing a mechanism for asking questions, it also implements simple input controls; think radio buttons and checkboxes, but in the console.

We'll also be using minimist to parse command-line arguments.

Here's a complete list of the packages we'll use specifically for developing on the command-line:

• chalk - colorizes the output
• clear - clears the terminal screen
• clui - draws command line tables, gauges and spinners
• figlet - creates ASCII art from text
• inquirer - creates interactive command line user interface
• minimist - parses argument options
• preferences - manage CLI application encrypted preferences

Additionally, we'll also be using the following:

• github - Node wrapper for the GitHub API
• lodash - JavaScript utility library
• simple-git - runs Git commands in a Node.js application
• touch - implementation of the *Nix touch command

Getting Started

Although we're going to create the application from scratch, don't forget that you can also grab a copy of the code from the repository which accompanies this article.

Create a new directory for the project. You don't have to call it ginit, of course.

mkdir ginit
cd ginit

Create a new package.json file:

npm init

Follow the simple wizard, for example:

name: (ginit)
version: (1.0.0)
description: "git init" on steroids
entry point: (index.js)
test command:
git repository:
keywords: Git CLI
author: [YOUR NAME]
license: (ISC)

Now install the depenencies:

npm install chalk clear clui figlet inquirer minimist preferences github lodash simple-git touch --save

Alternatively, simply copy-and-paste the following package.json file—modifying the author appropriately—or grab it from the repository which accompanies this article:

{
  "name": "ginit",
  "version": "1.0.0",
  "description": "\"git init\" on steroids",
  "main": "index.js",
  "keywords": [
    "Git",
    "CLI"
  ],
  "author": "Lukas White <hello@lukaswhite.com>",
  "license": "ISC",
  "dependencies": {
    "chalk": "^1.1.3",
    "clear": "0.0.1",
    "clui": "^0.3.1",
    "figlet": "^1.1.2",
    "github": "^2.1.0",
    "inquirer": "^1.1.0",
    "lodash": "^4.13.1",
    "minimist": "^1.2.0",
    "preferences": "^0.2.1",
    "simple-git": "^1.40.0",
    "touch": "^1.0.0"
  }
}

Now create an index.js file in the same folder and require all of the dependencies:

var chalk       = require('chalk');
var clear       = require('clear');
var CLI         = require('clui');
var figlet      = require('figlet');
var inquirer    = require('inquirer');
var Preferences = require('preferences');
var Spinner     = CLI.Spinner;
var GitHubApi   = require('github');
var _           = require('lodash');
var git         = require('simple-git')();
var touch       = require('touch');
var fs          = require('fs');

Note that the simple-git package exports a function which needs to be called.

Adding Some Helper Methods

In the course of the application, we'll need to do the following:

• Get the current directory (to get a default repo name)
• Check whether a directory exists (to determine whether the current folder is already a Git repository by looking for a folder named .git).

This sounds straight forward, but there are a couple of gotchyas to take into consideration.

Continue reading %Build a JavaScript Command Line Interface (CLI) with Node.js%

by Lukas White via SitePoint