Yargs is a great library to build command line apps, simply put, it will make the process of creating an application that runs in the console a breeze. What could make it even better? It's PIRATE themed (it's called YARgs you guys), making it officially the best tool ever.
In today's article we'll be creating a basic CLI from start to finish covering the following points:
<a name="setup"></a> Project set up
Setting up the project is very easy, start by doing the following:
We now have created our project's folder and initiated the
package.json file that contains its meta data.
Here's the file that was created:
We need to do a few adjustments to this file since we're creating a CLI. It should now look like this:
Here are the important changes to note:
- We've added a
binvalue, which maps the entry file we'll create later to its executable name (you can set it to whatever you'd like)
- We've set
preferGlobalto true, meaning that our package would prefer to be installed globally (via
npm install -gfor example)
Other tweaks include changing the
description, removing usuned
scripts, adding an
author name etc.
Before we can start coding our CLI, we need to install
yargs, do it like so:
npm install yargs
Let's get to it.
<a name="cli"></a> Creating a basic CLI
Yargs makes it very easy to parse command line parameters, many example projects can be found here.
We'll create a basic CLI that takes in a file as parameter and counts the number of lines it has.
To do so, start by creating our main script file.
And fill it with the following:
Let's cover everything line by line:
#!/usr/bin/env node is an instance of a shebang line that tells our system what interpreter to use to execute that file.
const argv = require("yargs") imports the
.usage('Usage: $0 <command> [options]') sets the usage information of your CLI that will be displayed when the
--help command is called.
.help('h') binds the help command to the option
.alias('h', 'help') creates an alias for the option
As you can see, this first step is extremely simple, and
yargs syntax is intuitive.
Next we'll add the
Just add the following lines to your already existing CLI:
Once again, let's review them line by line.
.command("count", "Count the lines in a file") creates a new command with the name
count and sets a description.
.example("$0 count -f foo.js", "count the lines in the given file") creates an example with a description, it will be displayed when the user calls the
--help option or when they mess up the command.
That's all great, but right now running
node yargs-example.js count doesn't do much, next up we'll require a file name and finish the CLI by counting and displaying its number of lines.
To do so, add the following:
Your file should end up looking like this:
.alias("f", "file") creates the alias
--file for the
.nargs("f", 1) sets the requirement of one argument for that option (the file name), otherwise display the
.describe("f", "Load a file") adds a description for the option.
.demandOption(["f"]) since we'll need a file name, we're demanding the option
Finally, let's add the program's logic like so:
And that's it, let's test it out.
Up until now, we've been running our program this way, but if we tried running it by calling it directly we would get an error.
$ line-count count -f package.json zsh: command not found: line-count
We can fix that by registering the binary (that we defined earlier as
bin in the
package.json) globally using the
npm link command.
In your application's directory, run the following:
Hurray ! You can now run your script locally like so:
yargs-example count -f package.json
<a name="deploy"></a> Deploying our CLI to NPM
Before deploying it, we'll need to add some information to our
Don't forget to replace the
repository info with your own, this will allow the npmjs.com website to fill up your future project's page.
engine value simply defines the minimum version of node your project should work on. Set it to whatever your project requires (depending on what JS features you may end up using, such as
Here are the next steps:
- Create an account on npmjs.com
- Run the
npm logincommand and input your information
- Run the
npm publishcommand which will automatically publish it in a matter of minutes
That's it ! If you wish to update your project in the future you'll need to change its version number in the
package.json file and then run the publish command again.
You now have your own NPM package published and accessible to the community, congrats !
If you have any questions, feel free to ask them on twitter @christo_kade.
Thank you for reading :-)