Command Line Functions are existing JavaScript functions that can be called directly from the command line without the need to manually write a wrapper CLI utility.
The easiest way to do this is to pass an existing JavaScript file that exports a
function to the clf
command line utility. clf
will analyze the function
signature of the exported function and automatically generate the corresponding
flags and options that you can then pass in through the command line.
For example, say you've already written a function called deploy
in
deploy.js
:
module.exports = async function deploy
({
dryRun = false /* Just print what this will do */,
regions = [] /* Which regions to deploy to */,
}, environment /* qa, staging, or production */ )
{
console.log(`Deploying to ${environment} to ${regions.join(", ")}!`);
}
You can treat this function a CLI utility by just calling clf
like so:
$ clf deploy.js qa --region aws-west-2
Deploying to qa to aws-west-2!
Not only that, but the comments will be appropriately interpreted for the
--help
command:
$ clf deploy.js --help
Usage: deploy [options] <environment>
Arguments:
environment qa, staging, or production
Options:
-d, --dry-run Just print what this will do
-r, --region <region...> Which regions to deploy to
-h, --help display help for command
Notice that clf
automatically inferred the types of the command line options
from the actual function definition. It knows dryRun
is a boolean from the
default parameter, and turned regions
function option into the singular
region
command line parameter that can be passed in multiple times, since it
noticed it was an array.
If you are writing a new function from scratch, you can choose to manually wrap
it in a call to toCLF
yourself, so that it can always be used both as a
function in a larger program, or called directly as a CLI app just using node:
const toCLF = require("to-clf");
module.exports = toCLF(async function deploy
({
dryRun = false /* Just print what this will do. */,
regions = [] /* Which regions to deploy to. */,
}, environment /* qa, staging, or production */ )
{
console.log(`Deploying to ${environment} to ${regions.join(", ")}!`);
});
This will work identically to our first function, except you can now call it
directly using node
instead of clf
, as if you had wanted it to be a CLI
app from the beginning, and again still without sacrificing its usage as an
importable normal function in the rest of your program:
$ node deploy.js qa --region aws-west-2
This actually makes to-clf
one of the easiest ways to write CLI apps in node!
to-clf
analyzes the AST of the function in question to build a CLI options and
arguments parser. Here are the details:
const toCLF = require("to-clf");
// toCLF will automatically interpret the destructured arguments of your
// function as CLI options.
module.exports = toCLF(function deploy
({
// toCLF will automatically detect the CLI option type based on the default
// parameter. For example, it knows the following option is a boolean:
dryRun = false /* This comment automatically becomes the help description. */,
// toCLF turns arrays into options you can pass multiple times
regions = [] /* Regions to deploy to. */,
// Unnamed arguments are also supported. If you leave out a default parameter,
// the option or argument becomes required.
}, environment /* qa, staging, or production */)
{
console.log(`Deploying to ${environment} to ${regions.join(", ")}!`);
});
To use the clf
command line utility, install it globally:
$ npm install to-clf --location=global
To use the toCLF
function, install it locally:
$ npm install to-clf