Skip to main content

How to Create a Command Line Interface with Node.JS (CLI, Zero Setup)

In this article, I will show you how to create a command line interface (CLI) using NodeJS.  I will also show you how to make it easy for engineers on your team to use it without having to clone it or run an installer.

These instructions were written for a Mac.

Prerequisites:​

It is assumed that you already have recent versions of npm and Node.js installed.

To run the command, your target users will need the following:

  • npm 7.x installed
  • node installed
  • access to read the git repo where you will publish the utility

For this example, I used GitHub to publish the repo.

Step 1. Create a new project​

Open up a terminal window and run the following:

mkdir -p ~/projects/javascript/cli-hello
cd ~/projects/javascript/cli-hello

Step 2. Initialize the project​

To initialize the project, run this command:

npm init -y

That command skips over the prompts that create package.json and just uses the defaults.

Step 3. Edit package.json​

  • Open package.json in your favorite code editor
  • Replace the line for the "main" property with this line and save the file:
"bin": "./index.js",

Step 4. Create index.js​

  • Create index.js through the editor or via this command:
touch index.js

Step 5. Update index.js​

  • Open index.js, add this code, and save the file:
#!/usr/bin/env node

console.log("Hello world!")

The first line is very important to run as a node-based CLI.  Do not change or move it.

Step 6. Test the file locally​

  • Run this command to test the file:
node index.js

Verify that the hello message is printed to the terminal.

Step 7. Initialize git​

  • To initialize git for this project, run this command:
git init
  • Add the files (note the period (.) at the end of the command):
git add .
  • Commit the files:
git commit -m "feat: init commit"

Step 8. Create a git repo​

For this example, we want the user to be able to have the utility install itself automatically via the command line. To do that, the target users need to be able to read from your repo.  

  • To create a new repo in GitHub, browse over to this site and follow the instructions:
  • https://github.com/new

In my case, I created a public repo that can be found here:

If you have an internal or private repo, be sure to give target users access.

Step 9. Run the command​

Once the repo has been created or pushed:

  • Open up another terminal window so you are not pointing to the same folder as the project (so we can make sure the command will still work)
  • Run this command (substituting my repo path for yours):
npm exec -- https://github.com/mitchallen/cli-hello
  • You will get prompted with something like this:
Need to install the following packages:
  github:mitchallen/cli-hello
Ok to proceed? (y)
  • Press Y for yes

Because your computer didn't have the latest version installed, you were prompted to do the update.

  • Run the command again (again, substituting your repo for mine):
npm exec -- https://github.com/mitchallen/cli-hello

Notice that this time you weren't prompted to install it again.

You can experiment by changing the code, pushing a new version, and trying again.  If you made any changes, the next time you run the command you will get prompted again.

Step 10. Create an alias​

Because the command is long and complicated, you should provide your users with instructions to create an alias.

If they are a Mac user, they probably have zsh.  To add an alias for zsh, do the following:

  • Open ~/.zshrc in a code editor
  • Add this line (replacing my git URL with yours) :
alias hello="npm exec --yes -- https://github.com/mitchallen/cli-hello";
  • Save the file
  • From the command line, run this command:
source ~/.zshrc
  • Run the command:
hello
  • Verify that it outputs the message

The alias adds the --yes flag to skip prompting the user on updates.

You can call the alias anything you want.  It doesn't have to be hello.  Though I would suggest keeping it to one simple-to-spell word.  

tip

Make sure you aren't aliasing it to something that exists now or may be installed in the future on a user's machine.

Next steps​

Now that you have the basic skeleton and distribution in place, you can look at packages to process command-line arguments.

One package that I've used a lot is Commander.  I'll add a reference at the end of this article.

Conclusion​

In this article, you learned how to:

  • Create a command line interface (CLI) using NodeJS
  • Publish it as a repo to simplify the distribution
  • Instruct the users on how to create an alias and suppress installation prompts

Source file​

References​

  • npmjs.com/package/commander - [1]
  • docs.npmjs.com/cli/v9/commands/npm-exec - [2]