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.
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
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.
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.
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);
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);
š£
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
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the āreport an issueā button at the bottom of the tutorial.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Sign up for Infrastructure as a Newsletter.
Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.
Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.