Anuradha Aggarwal

Posted on Aug 24

Building Your First CLI Tool

#webdev #programming #cli #beginners

Hello developers!! You must have use multiple CLI tools in your everyday development like echo, ls, cd etc.

Let’s try to understand it in a better way by creating your own simple CLI tool.

In this article, we will create a simple Calculator CLI tool.

🎯 What is CLI Tool?

A CLI (Command Line Interface) tool is just a program you run in the terminal by typing commands with your keyboard, instead of clicking buttons in a GUI (Graphical User Interface).

🎯 Project Setup

Setup the Project with initial command

npm init

Create a folder named src in the root directory of your project.
Inside src create a file called index.js This is going to be the entry point of our CLI.
In the package.json file, change the “main” part to src/index.js.
Now manually add another entry into the package.json file called bin and set its key to calc and it's value to ./src/index.js.

Your resultant package.json file would look like this:

{
  "name": "calculator-cli-tool",
  "version": "1.0.0",
  "description": "A CLI tool used for calculations",
  "main": "src/index.js",
  "bin": {
    "calc": "./src/index.js"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

The key calc, is the keyword for calling the CLI. This is the keyword that user will type in the terminal for using your CLI.

🎯 Commander

Commander is a popular Node.js library that makes it easy to build CLI tools.

What `commander` gives you?

Commands → Define sub-commands like add, multiply.
Arguments → Easily get values like 5 7.
Options (flags) → Support things like --verbose or --format json.
Automatic help → Generates --help output for free.
Versioning → Add --version easily.

Let’s install commander:

npm install commander

In src/index.js file:

#!/usr/bin/env node
const { Command } = require('commander');
const program = new Command();

program
  .name('calc')
  .description('A simple calculator CLI')
  .version('1.0.0');

// Command: add
program
  .command('add <a> <b>')
  .description('Add two numbers')
  .action((a, b) => {
    console.log(Number(a) + Number(b));
  });

// Command: multiply
program
  .command('multiply <a> <b>')
  .description('Multiply two numbers')
  .option('-v, --verbose', 'Show detailed steps')
  .action((a, b, options) => {
    const result = Number(a) * Number(b);
    if (options.verbose) {
      console.log(`${a} * ${b} = ${result}`);
    } else {
      console.log(result);
    }
  });

program.parse();

🎯 Link it globally

Now if you run the below command in your project folder, this creates a global symlink so you can use calc anywhere.

npm link

Now your CLI tool is ready to use anywhere in your system. Let’s try it now:

🎯 CLI Building Blocks

As you noticed in the above examples, there are multiple parts in the single commands, let’s break it down.

calc is the main command (the tool itself).
add, multiply represents sub-command (an action inside calc).
5, 7 represents the arguments (values you pass)
—verbose is a option which acts like a flag & modifies behavior

🎯 Wrap Up!!

That's all for this article. Thank you for your time!! Let's connect to learn and grow together. LinkedIn Twitter Instagram

Top comments (11)

Pranamya Rajashekhar • Aug 26

Ohhh this gives me so many ideas! Going to try it out for sure!

Jay • Aug 25

I love this. I'm a big fan of using the terminal as much as possible but I never tried to make a program or tool directly inside it. I might have to give this a try.

Debajyati Dey • Aug 28

Nice Write Up!

You may also like to have a read on my article that explores how to add oauth authnetication in your JS based CLI tools!

Integrate GitHub Login with OAuth Device Flow in Your JS CLI

Debajyati Dey ・ May 20

#cli #github #oauth #javascript

Pal Bronlund • Aug 27 • Edited

For the love of god, stop with the JavaScript all over the place already! It's made for doing stuff inside a browser, not for letting web developers ruin a perfectly good backend :)