By the end of this tutorial, you'll be familiar with the fundamentals of CLI tools, why they're invaluable for automating tasks, and how Node.js makes it easy to create them. We're going to build a simple but practical tool that converts Markdown files to HTML, setting the stage for your journey into creating more complex tools.

Why CLI Tools Are Awesome

Let’s cut to the chase—why even bother with CLI tools? Well, if you’ve ever had to repeat the same task over and over, a CLI tool can save you from that endless loop. Automating mundane tasks, handling files, launching servers, or deploying applications, all from a single command, is incredibly useful for developers.

Here’s why they’re fantastic:

• Speed up your workflow: Want to spin up a local server or convert a bunch of files with a single command? A CLI tool does that faster than opening apps and clicking through menus.
• Powerful automation: CLI tools shine when they’re used to automate repetitive tasks. Whether it’s deploying code or formatting files, they take care of the grunt work.
• Cross-platform consistency: A CLI tool works the same way on any operating system. If it works on Linux, it’ll work on Windows and macOS, too. This makes them a great fit for teams working across different platforms.
• Niche tools, low competition: Want to build something that only solves a specific problem, like converting Markdown files to HTML? There’s a decent chance someone else hasn’t already built it—or if they have, your version might be better. CLI tools have a unique space in the development world: the more specific the problem, the less competition you'll face.

You don’t need to be the biggest fish in the ocean to make an impact here. Some of the most popular developer tools are niche CLIs that handle one or two things exceptionally well.

What We’ll Build

Let’s start with something simple but useful—a Markdown-to-HTML converter. Markdown is a lightweight markup language that’s popular among developers for writing README files, documentation, and blog posts. But when you need to convert that Markdown to HTML (so it’s web-ready), doing it manually can get annoying, especially if you’re working with multiple files.

Our goal is to build a CLI tool where you can run a command like:

$ md2html example.md

And bam! You get an HTML file in return:

$ md2html example.md
Converted example.md to example.html

This tool will read your Markdown file, convert it into HTML, and save the output in a new file—all from the terminal.

This is a great starting point because:

1. It’s practical (you could actually use this in your workflow).
2. It touches on key aspects of building a CLI tool: reading files, processing data, and outputting a result.

We’ll take this example and build on it throughout the course, adding features and refining it.

Installing Node.js and Setting Up the Environment

First things first: you’ll need Node.js installed on your machine. If you’ve already got it, great! If not, don’t worry—it’s a breeze to install.

1. Download and Install Node.js:

   • Head over to the Node.js official website. You’ll see two options: LTS (Long-Term Support) and the latest version. LTS is more stable, so if you’re unsure, grab that.
   • Once downloaded, follow the instructions to install it on your machine.

2. Check if Node.js and npm are installed: After installation, open your terminal and run these commands to check that everything's set up properly:

   node -v
   npm -v
   

   If these return a version number, you’re good to go!

3. Set up npm for managing dependencies: npm (Node Package Manager) comes with Node.js and will help us manage any extra packages we need. We’ll also use it to initialize our project. So, let’s start by setting up a new folder for our project and running npm init:

   mkdir md2html-cli
   cd md2html-cli
   npm init
   

   This command will prompt you with a few questions (name, version, description, etc.). You can either answer them or just press enter to use the defaults. This creates a package.json file, which will hold all the metadata about our project.

Now that Node.js is installed, and npm is set up, we’re ready to start building.

Building Your First Simple CLI

Here’s where things get exciting! We’re going to write a script, turn it into a CLI tool, and call it from the terminal.

1. Create the entry point file: In the root of your project folder, create a file named index.js. This will be the main script file for your CLI.

   touch index.js
   

2. Add a simple script: Open index.js and add the following code:

   console.log('Hello from your first CLI tool!');
   

   Save the file. We’ll start small to see how this works before diving into file reading and HTML conversion.

3. Make the script executable: To run this script as a CLI tool from anywhere, we need to make it executable. We do this by adding a shebang line (#!/usr/bin/env node) at the top of index.js:

   #!/usr/bin/env node
   console.log('Hello from your first CLI tool!');
   

   This line tells your operating system to run the script using Node.js.

4. Update package.json: We also need to tell npm that index.js is the main file for our tool. Open the package.json file and add the following under the "main" section:

   "bin": {
     "md2html": "./index.js"
   }
   

   This tells npm that when we install this tool globally, it should create a command called md2html that points to index.js.

5. Make the script globally executable: Now, let’s link this tool globally on your machine so you can run it from anywhere. Run the following command in your terminal:

   npm link
   

   This creates a symbolic link between your local project and your global node_modules, allowing you to run md2html like any other terminal command.

Testing the CLI Locally

Now for the fun part—let’s test the tool! In your terminal, type:

md2html

You should see:

Hello from your first CLI tool!

Boom! You’ve just created your first CLI tool! It's basic for now, but you’ve got a working foundation to build on.

Troubleshooting:

• If you get a “command not found” error, make sure you ran npm link correctly. This is what registers the command globally.
• Also, double-check that #!/usr/bin/env node is at the very top of your index.js file.

Takeaway

Look at that—you’ve just built your first Node.js CLI tool! Sure, it’s simple for now, but the important part is understanding how to create a command-line script, make it executable, and call it from the terminal. You’ve set the stage for bigger things!

Next up, we’ll add some real functionality by reading Markdown files, converting them to HTML, and expanding your CLI's capabilities. Get ready to dive deeper into the world of CLI tools!