How to build a Node.js CLI

In this video, we are going to create a name CLI. For that, you are going to create an account on github.com and npmjs.com, if you don't have one. And then I'm going to call the CLI awais.

For example, this could be your name something unique that is isn't already, you know, published on npmjs.com. And then we are going to publish the CLI on npm. So everyone in the world or maybe an astronaut sitting in the outer space could probably use the CLI to know who you are.

You would be using the CLI by typing in npx awais in your terminal. So that, uh, and the CLI is basically going to return my name and my biography, you know, a little bit, a couple of lines about who I am. Okay.

Let's get started. If you don't have a github.com account, go ahead and sign up, and then you'll be able to click here and create a new repository. Or you can just type in repo.new and press enter.

Here you can create a new repository. I'm going to call this repository awais. Get to know Awais via npm.

Just run npx awais, right? I can backtick here. There you go!

So now that I have created this repository, I'm going into my terminal and I'm going to git clone it. cd to awais. Nice! The next thing is we are going to create an account on npmjs.com.

You can definitely go-ahead and sign up from their website. But since this is a course about creating CLIs, how about we use npm CLI to create a new user? If you go to npm help, you can see there are a bunch of commands that you can run.

One of these commands is adduser. So go ahead and type in npm adduser. This is if you don't have an npmjs account.

Type in a username that is quite peculiar to use and probably quite unique. So it is not already existing on npmjs. For example, you could have a username mynameisawais or whatnot.

And then type in a password and finally an email ID, which is going to be public. This is the email ID which is going to be used to publish npm packages on npmjs.com. So add your email ID here.

And then you just go ahead and press return or press enter. And it will go ahead and create this username for you. And if it doesn't create this username, it'll probably give you an error or something that this particular username already exists, and you need to create a new user or use different username or whatnot.

And when this happens, npmjs is going to send you an email on the email ID you used here. Go ahead and open that email and verify your npmjs account. This is quite important because without this particular step, you're not going to be able to, uh, you know, publish packages to npmjs.com.

Okay I'm just going to cancel this one because I already have an account. Now, if you are logged in, if you have an account, you should be able to check it npm whoami. And as you can see, I'm already logged in.

My username is ahmadawais. npmjs.com/~ahmadawais is how you can probably go to my profile. Okay. Now let's start writing code.

I'm going to use VSCode for this. So code . would open this particular folder in VSCode. So whenever you start a project for nodejs CLIs, you create a folder and then you create an index.js file inside of it.

And here's where we code for this particular CLI. We've want to run the CLI and it should console log my name. This should be pretty simple, right?

How about I start with just console logging my name. So that would be Ahmad Awais. Now how do you think I can run this particular script?

Uh, I'm not sure. I'm going to open up terminal inside of VSCode. And then I'm going to type in index.js.

And I see command not found: index.js. Basically. my shell does not understand what I'm trying to do. It has no command registered against index.js.

Maybe if I tell it that I'm going to run a script inside this particular directory and an index.js file is what I'm going to run then we will see better results. Well, let's hold for it and press enter. Okay.

So now it says permission denied. What is happening? If I type in ls hyphen al to see and list all the files in this particular directory called awais, there is an index.js file.

And if you take a look at the permissions of this file, I can only read this file. This r basically says that I can only read this file. This file can not be executed as a shell script.

So how about I give it an executable right. A permission to be executed. For example, the let's give this index.js file the permission so that it can be executed.

That permission would be x. For that, I'm going to type in chmod +x, and then the name of the file. Now, if I list all of the files, you can see that this particular index.js file is now executable.

So I'm going to type in clear to clear the terminal. And let's try it again. ./index.js. Okay.

Syntax error. It hasn't still run the CLI and it is sort of a shouting at us what is this? What is this syntax?

It has an unexpected token or whatnot. What is happening here? What's happening here is basically we are trying to run this particular JavaScript file in our command line which is a shell and it can only understand shell script.

It is trying to understand this as a shell script language not as JavaScript. We need some kind of way to tell our terminal that please run this script with nodejs. For example, if I try to run it with nodejs.

Let's see what happens. Oh! I get that console log that I had written here.

Ahmad Awais. So we know that node can run this file but our terminal, the shell cannot. How do we fix this?

Let's clear this up. To fix this thing, what I'm going to do is I'm going to add Shabang here. So Shabang with a funny name is actually a hashtag with a pound sign where you basically tell your terminal that this particular file is going to be run with nodejs.

For that, we write this Shabang hashtag with bang sign and then usr without an e. This is a directory in your computer. bin env and then node. This Shabang is basically telling our terminal to run this particular script with nodejs.

If this would have been a bash file, we would have written bash here or Python if this would have been a CLI built with Python. But for the course, I'm going to type in node. So this hashtag in bang sign, call Shebang or Shabang or hash bang or hash pound sign, and this basically tells our terminal that this particular index.js file should always be executed with nodejs.

So I'm going to save this. Open up the terminal. And let's run this particular file again.

Now I'm not going to use node and let's see if this executes and there you go. Now we are able to execute this script in a command line. But the funny thing is I don't want to, you know, use ./index.js to kind of run the CLI.

I want to kind of say, let's say awais and it should run this particular CLI. How do I make that happen? There should be a way to define what command should I run or what command to the CLI register, which I could run to print this particular, you know, uh, run this particular CLI that prints Ahmad Awais.

What I want to do is I want to run, just say awais, and I want this awais command to run the CLI. But my terminal basically say is that there's no command registered against this, you know, these words of awais. So let's clear this up and think about what we can do here.

In the JavaScript ecosystem for npmjs, we actually register and define all of these commands in a file called package.json. So let's go ahead and create package.json file. The package.json file lives in the root directory of our, you know, project it's a JSON file.

And the first thing I'm going to give it is the name of our particular CLI here, which is awais. Make sure that you only use the kebab case here and everything you write in the name should be lowercased. And then I'm going to give it a version.

And I'm going to call that 1.0.0. This is going to be a major version. This is called major, minor and then the patch version.

I'm going to explain these semantic versions later. Now I'm going to define the command that when run should run this particular CLI. For that we are going to define the bin keyword here and here it is where we define the command.

This command is going to run index.js file in our project here. So this command should be called awais, right? So now when you install this package and run awais, you will be able to run index.js file, which console logs my name.

Make sense. Let's try it out. Right now, if I write awais, my terminal shout at me and says that awais is not a registered command.

But before I publish this package to the world out there, I want to test it locally. And for that, I'm going to basically create a local link for this file. For that, I'm going to write in npm link.

When I ran npm link, a couple of things happened. First of all, I got all of these warnings about that there is no description or a policy or license field in my package.json file that we can always add later. But what really happened was that this package.json file.

This package that we have just created, got installed globally in our machine. So basically. npm links installs your package in your computer. It is equivalent to installing a package with npm install, hyphen hyphen global, and then your package name here, right?

This is the directory where my node modules are going to be installed. As you can see, there's an awais directory here in these node modules, global node modules. And then there's an index.js file, which is what we can run by writing this particular command awais.

I know this is extra information, but just so that, you know, now you can start running that particular command. Now, if I type in awais and hit enter, it basically runs this particular file. And you can see Ahmad Awais written here.

And the fun thing about this is that now this particular package is globally installed. And it's already linked to your local code. What I mean by that is if you go ahead and change something here, for example, software engineer and run the command again, you'll see that the output has changed.

So now I can basically do anything with the CLI and test it locally because I have npm link, this particular package globally inside this computer I'm using right now. And if I want to ever uninstalling this global package, all I have to do is npm uninstall hyphen G for the global tag, and then the package name awais. Now if I run awais, it is again going to shout at me saying command not found.

So a little bit of a recap here. If you've want to locally test your node CLI, you can go to the root of that directory, where you have that package. For us, this is the awais directory.

For you, this is going to be a directory against your name and just type in npm link. npm link basically links your local package and installs it as a global node module. Now you can run this global module whenever you like. Since I'm using string literals here, the string with backticks, I can basically use a multiline string here.

So I'm going to just go ahead and do that. And then I'm going to type in my bio. And finally, how about we add some social media links here.

Twitter and then open book for GitHub. And then my blog, I'm just going to add this dude with glasses. Let's call it blog.

So there you go. And finally, I'm going to leave an empty line here. Now, if I run the CLI, you know, the CLI basically is defining who I am, a little bit about my bio and a couple of links that I can basically click by pressing command or option/alt in my computer.

Okay. Our CLI looks great. I'm going to go ahead and commit our CLIs as the first version to GitHub.

Just for the keepsake so I don't lose this code. Now let's go ahead and publish this CLI on npm. For that, make sure that you are logged in with npm whoami.

So as you can see, it prints out my username for npmjs.com, which means I'm logged in. And then I just need to write in npm publish. And there you go.

I have published a CLI called awais with a major version 1.0. All of this information basically tells me that all of these files were uploaded and now have awais CLI basically lives on npm. Let's go ahead and check if that is actually true.

A shortcut to do that is by typing npm.im/name of your package. And this will take you to npmjs.com/package/awais, which is actually the link where your package gets published. And as you can see, the last publish was about a minute ago and here's the CLI with no readme found, no keywords whatsoever, which we are going to fix in the next couple of videos.

Now I'm going to uninstall the local version we just install using npm link. I can verify that by typing in awais. And as you can see, there is no command called awais right now.

So now that our CLI is published on npmjs.com, what we can do is we can basically use the package name, which is awais, which is also denoted here in the URL and run the CLI using npx. Let's try it out. npx awais. npx is going to go ahead and install this particular CLI and then execute it. So there you go.

It's saying Ahmad Awais, my bio and the links we had written. And that's pretty much about it. This is how you create your first CLI and publish it on npmjs.com.

Anyone could use npx to run your CLI right away.