How to Build and Publish a Simple Node.js CLI Tool

1. Introduction

This tutorial is aimed at developers with JavaScript experience who want to learn how to create a command‑line interface (CLI) tool. It walks through building a minimal CLI from zero to a publishable npm package.

2. What is a CLI Tool

CLI stands for Command‑line Interface, a user interface operated by typing textual commands. Common examples include system commands (cd, mkdir), scaffolding tools (create‑react‑app, vue‑cli), preprocessors (less, sass), testing tools (mocha, karma) and build tools (webpack, gulp).

3. Why Build Your Own CLI

Instead of repeatedly typing long commands like ifconfig and parsing output, a custom CLI can provide a concise command (e.g., ip ) that directly returns the desired information.

4. Developing the CLI Tool

4.1 Ensure Node.js is installed.

4.2 Create a project folder and an index.js file:

mkdir ip-cli && cd ip-cli
touch index.js

Edit index.js with the following content:

const os = require("os")
const ip = os.networkInterfaces().en0[1].address
const options = process.argv.slice(2)
if (options[0] === '-v') {
    console.log('v1.0.0')
} else {
    console.log(`your ip is: ${ip}`)
}

Run the script with node index.js to see the output.

4.3 Add a shebang line to specify the interpreter:

#!/usr/bin/env node

const os = require("os")
const ip = os.networkInterfaces().en0[1].address
const options = process.argv.slice(2)
if (options[0] === '-v') {
    console.log('v1.0.0')
} else {
    console.log(`your ip is: ${ip}`)
}

Make the script executable with chmod +x index.js .

4.4 Add the script to a directory in $PATH (e.g., /usr/local/bin ) using a hard link:

ln index.js /usr/local/bin/ip

Now the custom command ip works directly.

5. Managing the Project with npm

5.1 Initialize the npm project:

npm init -y

Resulting structure:

.
├── index.js
└── package.json

5.2 Define the bin field in package.json to map the command name to the script:

{
  "name": "ip-cli",
  "version": "1.0.0",
  "main": "index.js",
  "bin": { "ip": "./index.js" },
  "scripts": { "test": "echo \"Error: no test specified\" && exit 1" },
  "license": "ISC"
}

5.3 Test the CLI locally with npm link , which creates a global symlink.

5.4 Publish the package:

Login with npm login and verify with npm whoami .

Run npm publish . If the name is taken, add a scope (e.g., @qianxuemin/ip-cli ) and set the package to public.

After publishing, others can install the tool globally with npm install -g @qianxuemin/ip-cli .

6. Tips and Best Practices

Include a comprehensive README.md .

Provide --help and --version options.

Show progress indicators or loading messages.

Check name availability on npm before publishing.

Use .npmignore or the files field to control published files.

7. Common Libraries for CLI Development

Popular Node.js modules that simplify CLI creation include commander , inquirer , chalk , shelljs , ora , progress , blessed-contrib , and download-git-repo .

8. Conclusion

The article demonstrates the end‑to‑end process of building, testing, and publishing a simple Node.js CLI tool, offering practical advice and resource links for developers to create their own efficient command‑line utilities.