Yargs Interactive: Create CLI tools for humans and non-humans

One of the most amazing things about Node.js is that you can use it to create a wide variety of applications, like powerful, real-time applications, but also simple command line interfaces (CLI) tools.

When creating CLI tools, the first challenge to solve is usability. In other words, how can you help users to use this tool effectively? And for CLI tools, this usually means what and how many configuration arguments it has.

These are the challenges I love to solve because, if you do it, right, your tool is definitely going to be a game changer in the open source community.

Fortunately, in the Node.js world, some de-facto tools help you with the setup of your CLI. Yargs, for instance, solves the job of parsing the arguments sent to your CLI and generating a basic user interface with help and documentation. Using this tool, you simplify the adoption of your tool without writing a single line of code.

But, as your CLI becomes more complex, more flags and commands will be added, making its use surprisingly difficult for humans. Not only that, what happens when there are some values that you cannot set by default, like passwords or any other sensitive information. Generally speaking, what can you do when you need direct intervention from users? Inquirer solve this by prompting simple and complex questions to users, like lists, checkboxes, etc.

In the world we live in, we usually need to automate tasks in CI tools (where yarn shines). But we also need useful tools for humans (what inquirer does best). The question is..

What can we do when we need a combination of both worlds? (interactive & non-interactive CLIs).

Introducing yargs-interactive

yargs-interactive

Yargs Interactive is a library that provides interactive (prompt), non-interactive and mixed-mode for CLI tools. It helps you to develop a CLI that can be consumed by users and automated tools (CIs, scripts, etc.).

How to install it

In your terminal, run the following:

npm install -S yargs-interactive

Then, add this code in your CLI main entry point code to activate the tool right after your CLI starts:

Yargs Interactive: Basic setup

By simply wrapping your CLI code with this tool, you will get all the information you need from the user.

How to use it

Let’s say you are working on a CLI named my-cli.js and you need to get some information from users to execute some process. You can let yargs-interactive handle this for you, by simply wrapping your code with it (see the image below).

#!/usr/bin/env node
const yargsInteractive = require(‘yargs-interactive’);
const options = {
  name: { 
    type: ‘input’, 
    default: ‘A robot’, 
    describe: ‘Enter your name’
  },
  likesPizza: { 
    type: ‘confirm’, 
    default: false, 
    describe: ‘Do you like pizza?’
  },
};
yargsInteractive()
  .usage(‘$0 <command> [args]’)
  .interactive(options)
  .then((result) => {
    // Your business logic goes here.
    // Get the arguments from the result
    // (e.g. result.name)
    myCli(result.name);
});

Then, run the CLI with the --interactive flag to tell the tool that it needs to prompt questions to the user.

➜ node my-cli.js --interactive

If you want to use always interactive mode, just set the --interactive parameter to true by default in the options you sent to the tool.

const options = {
 interactive: { default: true },
 ... /* other options */
};
yargsInteractive()
  .usage('$0 <command> [args]')
  .interactive(options)   
  .then((result) => {     
    // Your business logic goes here.     
    // Get the arguments from the result     
    // (e.g. result.name)
    myCli(result.name);
});

And then you can call your CLI with no parameters.

➜ node my-cli.js

What type of prompts are supported?

It provides all prompt types Inquirer has.

What about automated environments?

If you want to use your CLI in automated environments, and you need special arguments, you can either:

1. Run the CLI by sending these special arguments.

➜ node my-cli.js --name=”Android 18" --likesPizza

2. Pro tip: don’t send any argument. The tool will use the default ones (which, could be exactly the ones you need in the automated environments).

Also, don’t forget that if you have set the --interactive argument to true by default, you will need to set it tofalse in automated environas follows:

➜ node my-cli.js --name=”Android 18" --likesPizza --no-interactive

Note: there is an open issue in Yargs to include some level of interactive support in the tool. If you want to see this happening, and/or want to help with making it happen, please chime in.