make-cli: Declarative CLI Framework

6.0.2 · active · verified Wed Apr 22

make-cli is a declarative framework for building command-line interfaces in Node.js, distinguished by its streamlined approach that centers around a single configuration object and a single function call. It aims to simplify CLI development by abstracting away much of the boilerplate often associated with argument parsing and command definition. The current stable version is 6.0.2, with major versions typically aligned with Node.js LTS releases (e.g., v5 required Node.js >= 20, v6 requires Node.js >= 22). Patch and minor releases occur regularly to address bugs and introduce minor enhancements. Built on top of Commander.js, make-cli leverages its robust parsing capabilities while offering a more functional and declarative API. This design makes it particularly appealing for developers who prefer a concise and config-driven style for their CLI tools, differentiating it from more imperative or class-based alternatives by providing a highly approachable entry point for creating complex command structures.

Common errors

```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use ES module `import` syntax in a CommonJS context (e.g., a `.js` file without `"type": "module"` in `package.json`, or an older Node.js version).

fix Ensure your project's `package.json` includes `"type": "module"`, or rename your file to `.mjs`. Alternatively, ensure your Node.js version meets the minimum requirement for `make-cli` (v6 requires Node.js >= 22).
```
make-cli: command not found
```
cause The CLI executable is not correctly configured in your `package.json`'s `bin` field, not installed globally, or the script lacks execution permissions.

fix If publishing, add `"bin": "./cli.js"` (or your script path) to `package.json`. Locally, run `npm link` in your project directory for development, or ensure your script has execution rights with `chmod +x ./cli.js`.
```
Error [commander.invalidArgument]: argument 'value' is invalid, choices are 'foo', 'bar', 'baz'
```
cause The value provided for an option with `choices` specified in the configuration does not match any of the allowed choices.

fix Ensure the argument passed for the option (`--value` in this example) is one of the predefined `choices`. For example, use `--value bar` instead of `--value invalid`.

Warnings

breaking Version 6.0.0 and above of make-cli requires Node.js version 22 or higher. Older Node.js versions will result in compatibility issues.
Fix: Upgrade your Node.js environment to version 22 or newer, or downgrade make-cli to a compatible major version (e.g., v5 for Node.js >= 20).
breaking Version 5.0.0 of make-cli introduced a minimum requirement of Node.js version 20. Users on older Node.js versions will encounter errors.
Fix: Upgrade your Node.js environment to version 20 or newer, or stick to make-cli v4.x.
gotcha In `make-cli` versions prior to 6.0.2, CLI actions or handlers might not always wait for asynchronous operations to complete before exiting, leading to premature process termination.
Fix: Update to make-cli version 6.0.2 or newer to ensure CLI actions correctly wait for all promises to resolve before the process exits. Ensure your action/handler functions are `async` and `await` all relevant promises.

Install

npm install make-cli npm
yarn add make-cli yarn
pnpm add make-cli pnpm

Imports

makeCli
wrong:
```
const makeCli = require('make-cli');
```
correct:
```
import makeCli from 'make-cli';
```
make-cli is primarily an ESM-first package, especially from v5 onwards requiring recent Node.js versions. Direct CommonJS `require` might lead to errors.
MakeCliOptions
```
import type { MakeCliOptions } from 'make-cli';
```
For TypeScript users, import types separately for configuration options.
makeCli (named import)
wrong:
```
import { makeCli } from 'make-cli';
```
correct:
```
import makeCli from 'make-cli';
```
The primary export is a default export, not a named export.

Quickstart

This example demonstrates defining a CLI with global arguments and options, an main action handler, and a subcommand. It includes TypeScript types, async operations, and option validation with 'choices'.

#!/usr/bin/env node

import makeCli from 'make-cli';
import { resolve } from 'path';

interface MyCliOptions {
  yes?: boolean;
  value: string;
  force?: boolean;
}

makeCli<MyCliOptions>({
  version: '0.1.0',
  name: 'my-cli',
  usage: 'A simple demonstration CLI for make-cli',
  arguments: '<remote> [extra]',
  options: [
    {
      name: '-y, --yes',
      description: 'Skip interactive prompts and confirm actions',
      default: false
    },
    {
      name: '--value <value>',
      description: 'Specifies an important configuration value',
      defaultValue: 'default_foo',
      choices: ['default_foo', 'bar', 'baz']
    }
  ],
  action: async (remote: string, extra: string | undefined, options: MyCliOptions) => {
    console.log(`Executing action for remote: ${remote || '[no remote]'}`);
    console.log(`Extra argument: ${extra || '[no extra]'}`);
    console.log(`Options: Yes=${options.yes}, Value=${options.value}`);
    
    if (options.yes) {
      console.log('Skipping interactive confirmation due to --yes flag.');
    } else {
      console.log('Performing interactive confirmation...');
    }
    console.log(`Resolved path example: ${resolve('.')}`);
    await new Promise(resolve => setTimeout(resolve, 100)); // Simulate async work
    console.log('Main action completed.');
  },
  commands: [
    {
      name: 'push',
      description: 'Pushes changes to the remote repository',
      arguments: '<remote>',
      options: [
        {
          name: '-f, --force',
          description: 'Force push',
          default: false
        }
      ],
      handler: async (remote: string, { force }: { force: boolean }) => {
        console.log(`Executing 'push' command to ${remote} with force=${force}`);
        await new Promise(resolve => setTimeout(resolve, 50));
        console.log('Push command executed.');
      }
    }
  ]
});

view raw JSON →