toCLF ("to command line function")

Command Line Functions are functions that can be called directly from the command line.

The easiest way to use to-clf is to just call the clf command line utility by passing it an existing JavaScript file and it will run whichever function this file exports as a CLI app, automatically analyzing its parameters and turning them into command line parameters you can pass in.

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 just call it with clf like so:

$ clf deploy.js qa --region aws-west-2
Deploying to qa to aws-west-2!

Not only that, 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!

How Does this Work?

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(", ")}!`);
});

Installing to-clf

to-clf is available on npm.

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