Tutorial
Improve Your Command-line Scripts by Including a Usage Guide
While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.
If you’re already familiar with JavaScript in your day to day programming adventures, it wouldn’t be too shocking if you reached for it when you need to write a quick command-line script. Quick scripts have a tendency to be somewhat dirty, usually lacking usage documentation. The command-line-usage
package makes it easy to add in professional-looking script usage output to your quick and dirty scripts.
Getting Started
To get started with command-line-usage
, you’ll need to add it to via your favorite package manager:
# npm
$ npm install command-line-usage --save
# Yarn
$ yarn add command-line-usage
Be sure to import command-line-usage
:
const cliUsage = require('command-line-usage');
While this article is focused on the command-line-usage
package, it’s worth noting that the package leverages the chalk
template literal syntax and plays quite nicely with chalk
methods like chalk.red()
.
If you would prefer to use the chalk
methods instead of the template literal syntax, be sure to also import chalk, which is a dependency of command-line-usage
:
const chalk = require('chalk');
For a more in-depth look at chalk
you can check out our article Styling Output from Command-line Node.js Scripts with Chalk
Basic Usage
With everything installed and properly imported, we can build out some simple usage information:
const sections = [
{
header: '🐊 Alligator.io CLI Script',
content: 'From {bold your friends} at {underline Alligator.io}',
},
{
header: 'Usage',
content: [
'% script {bold --file} {underline /path/to/file} ...',
],
},
];
const usage = cliUsage(sections);
console.info(usage);
The sections
array contains groupings of information you’d like displayed in your usage information. You can have as many sections as you’d like with different options within each section.
Running the sections
array through command-line-usage
will generate a string which we can then log to the console.
List Arguments
To list out the arguments for a script, you can use the optionList
property which takes a series of options:
const sections = [
{
header: 'Mandatory Options',
optionList: [
{
name: 'file',
alias: 'f',
type: String,
typeLabel: '{underline /path/to/file}',
description: 'The file to do stuff with',
},
],
},
{
header: 'Optional Stuff',
optionList: [
{
name: 'letters',
alias: 'l',
type: String,
typeLabel: '{underline letter} ...',
description: 'This option takes multiple values',
multiple: true,
defaultOption: 'a b c',
},
{
name: 'help',
alias: '?',
type: Boolean,
description: 'Print this usage guide.',
}
],
},
];
const usage = cliUsage(sections);
console.info(usage);
The command-line-usage
package takes care of all of the hard work by spacing out the arguments in a table layout.
Table Layout
Speaking of the table layout used when presenting the argument list, you can also use the table layout when passing the content
property an array. Simply pass-in an array of objects instead of strings and command-line-usage
will format the information like a table:
const sections = [
{
header: 'Table Layout Example',
content: [
{
desc: 'More great Alligator.io articles:',
url: '{underline https://alligator.io}',
},
{
desc: '`command-line-usage` on GitHub:',
url: '{underline https://git.io/fh9TQ}',
},
],
},
];
const usage = cliUsage(sections);
console.info(usage);
Having Some Fun
Sometimes you just want to have some fun. As mentioned earlier, command-line-usage
can leverage chalk
which means you can spice up your usage output with a splash of color.
To get a little crazier, if you were to channel your inner Demoscene artist and put together some ASCII/ANSI art complete with escape codes, you’ll want to include the raw
property to ensure things are displayed correctly.
const sections = [
{
header: 'Raw Like Sushi',
raw: true,
content: [
'{red ,iiiiiiiiii,}',
'{red ,iiiiiiiiiiiiii,}',
`{red iii' 'ii'}`,
`{white '.________.'}`,
],
},
];
const usage = cliUsage(sections);
console.info(usage);
🍣
Conclusion
As amazing as the command-line-usage
package is at making it easy to generate script usage information, it’s still somewhat lacking. One thing to keep in mind is that the package doesn’t actually do any sort of command-line argument handling.
The actual handling of the command-line arguments will need to either be handled by rolling your own solution by parsing the argument vector process.argv
yourself or by leveraging a package like commander
.
For more information check out our article Handling Command-line Arguments in Node.js Scripts