How to create a Command Line Program with NodeJS

I’ve been playing a lot lately with NodeJS. It’s a great library and performs very well for backends of mobile and web applications. The community is growing very fast and there are new modules published or updated every day to NPM.

In this post I’m going to document the steps I follow to create a Command Line Program using NodeJS. This is very useful for encapsulating some logic in a program that can be executed quickly on your computer or even on a server. I have found this is a quick and easy way to automate some development tasks that I use every day. For instance, I’m working on a program that helps me to manage the state of a project, by moving the files from folders (development, testing and production) as the development cycle progresses. It’s easy to just copy and past the files between the folders, but it’s a lot cooler to execute a command and get it done for your in milliseconds. Let’s get started.

NodeJS and NPM

First, you need to make sure you have NodeJs in your system. Installation is very easy. NPM is the package manager for node, it’s a great tool, and it’s getting better every day. Installation is aslo super easy.

Get tour Source Control ready (optional)

This step is optional, but I really recommend you do it. It will help you as you progress in development of your tool. I use GitHub. It’s free for public repositories. If you want to host private ones, there is a small fee, based on the number of repositories you need to host.

You can also choose between the command line of a GUI program to manage your repositories, that’s completely up to you.

So, go ahead and create your project in GitHub and then clone it to your computer, so you can start working on it.

Project Structure

If you decided to follow this tutorial without using GitHub, just create the following files and folders in any location in your computer, other wise, if you cloned your GitGub project, you will work on the folder that was created after you cloned your remote repository.

You basically have to create 3 files. The README.md file where you document your program. A package.json file, where we will store some information needed to published the program to NPM and clitutorial, where we will add the code for the program. Here’s a screenshot of what you should have created so far:

Code your CLI

Now it’s time to code your program. In this example, we will create a very simple program that outputs some text to the console, base on some commands and actions that can be provided by you (more on that later), when you execute it.

Let’s edit clitutorial and add the following code. We are basically saying that the file will be executed by “Node”, and then that “Hello World” must be output to the console.

Save your file and execute it. You should see something like this:

If you see “Hello World” in the console, it’s working for you… great!

Make it More Powerful

Now, let’s make it more powerful, this has to be a real Command Line program, and we need a way to pass in information to the program, without changing the code, of course. And for that, we will use a Node module called commander. This module will parse commands and parameters for us, so we can write our code easily.

Let’s use NPM to install commander. Execute this command:

And you will see this:

Now, let’s see an example of how to use commander.

In line 3, we require the module and store it in a variable called program.

In line 6, we add a version for our program.

In line 9, we add a listener for the command “hi“. It can be anything you want. In this case the command doesn’t expect any text entered by the user.

In line 10, we add a description for the command “hi“. It will be use to generate the documentation of the program.

In line 11, we add the code that will be executed with the command “hi“. In this case it just prints out “Hi my Friend!!!” to the console.

In line 16, we have a second command, “bye“, and as you can see, it expects that the user enters some text, that will be stored in a variable called “name“, that we use in line 20.

In line 23, we catch all unknown commands that weren’t detected in the program. Here we can inform the user that a valid command wasn’t received or do a default action. That’s up to you.

Test Our CLI Program

We used commander because it give us some nice functionality out of the box.

For instance if you execute your program with the option -h, you will see all commands and options implemented in the program.

Now, let’s execute our two commands, “hi” and “bye”, just like this:

You will see the correspondent outputs in the console.

As you can see, it’s really easy to create a CLI program with NodeJs. You can make it do anything you want, this is just the foundation. Now let’s publish it to NPM so it’s easy to install and share

Publish to NPM

NPM makes it really easy to share your NodeJS programs to the world. There are only two steps 1) create a configuration file for your program, and 2) execute the command publish. My package.json looks like this:

So.. just execute this command to publish, once you have your package.json ready:

Summary

Well… these are the very basics of how to create your first NodeJS-based CLI program. You can find the code I used here in my GitHub repository.

The application can be found also in NPM, here.

To install it from  any computer, just execute this command:

 

The Discussion

6 Comments

  • Very easy to follow.. I just created my first CLI applications following your tutorial. Very well done. Cheers!

  • Great… just what I needed it.

  • I think the file has to be executable, has’t it?

    • You are absolutely right!

  • I love NodeJS :)

  • wow.. very well done. It’s a great idea to create this kind of command line applications application to automate development work. Thanks for sharing!

Leave a Comment


− 2 = two

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>