clite: A Lightweight CLI Framework

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module syntax (`import`) with clite, which is a CommonJS-only package.
  fix Change `import clite from 'clite';` to `const clite = require('clite');` in your main CLI entry file.

• ReferenceError: Promise is not defined

  cause Running clite on a very old Node.js version (pre-Node.js 4.0) where Promises were not natively supported, and the `es6-promise` polyfill included by clite is not effective or properly loaded.
  fix Ensure `es6-promise` is installed and that clite's internal polyfill is effective, or preferably, upgrade to Node.js v4.0 or higher where Promises are natively available.

• Error: Cannot find module './config'

  cause The main clite script cannot locate the configuration file specified in the `require()` call.
  fix Verify that the path to your config file passed to `require()` in your main script (e.g., `clite(require('./config'));`) is correct and relative to the calling script's location.

Warnings

• breaking clite has not been updated since March 2016, making it potentially incompatible with modern Node.js versions (e.g., v16+, v18+, v20+) and newer JavaScript language features (ESM). Its internal dependencies may also be severely outdated.
  Fix: Consider migrating to a actively maintained CLI framework (e.g., `oclif`, `commander`, `yargs`) or thoroughly test compatibility with your target Node.js runtime and dependencies using a lockfile.
• gotcha By default, clite catches all exceptions originating from command modules and exits the process with a non-zero code, printing the error message to stderr. This prevents higher-level application-specific error handling.
  Fix: To handle errors within your application code, set the `return: true` property in your clite configuration. This will cause errors to be returned as rejected promises to your main script instead of causing a `process.exit(1)`.
• gotcha clite relies on internal dependencies like `yargs` and `abbrev`. If these dependencies have had breaking changes in their latest versions that conflict with the specific versions clite expects (which are likely old), it could lead to unexpected behavior or runtime errors.
  Fix: Ensure your project uses a lockfile (`package-lock.json` or `yarn.lock`) to maintain consistent dependency versions. If conflicts arise, manual intervention or a full migration to a more current framework might be necessary.
• deprecated The project uses CommonJS modules exclusively, which is considered a legacy module system in modern Node.js development. It does not support native ES Modules (`import`/`export` syntax) without transpilation or specific Node.js loader configurations.
  Fix: Develop new CLI projects using native ES Modules with a modern CLI framework. For existing clite projects, continue using CommonJS or plan for a full migration.

Install

• npm install clite npm
• yarn add clite yarn
• pnpm add clite pnpm

Imports

• clite
  wrong:

  import clite from 'clite';

  correct:

  const clite = require('clite');

  clite is a CommonJS module and must be imported using `require()` in Node.js environments. Direct ES module `import` syntax will result in an error.
• Configuration Object
  wrong:

  clite({ commands: { /* ... */ } });

  correct:

  clite(require('./config'));

  The primary `clite` function expects a configuration object, typically loaded from a separate CommonJS module file using `require()`.
• Command Module
  wrong:

  export default function myCommand(args) { /* ... */ };

  correct:

  module.exports = function myCommand(args) { /* ... */ };

  Command modules are dynamically loaded by clite and must use Node.js CommonJS `module.exports` syntax to expose their functionality.

Quickstart

Demonstrates setting up a basic `clite` application with a default command, a named command (`greet`), and an asynchronous command (`delay`), including configuration for options, booleans, aliases, and a help file. The code shows how `clite` consumes a configuration object and how individual command modules are structured.

/* cli.js */
#!/usr/bin/env node
const clite = require('clite');
const path = require('path');

// Load configuration for the CLI application
clite(require('./config'));

/* config.js */
module.exports = {
  commands: {
    '_': path.join(__dirname, 'commands', 'default'), // Default command if no argument provided
    'greet': path.join(__dirname, 'commands', 'greet'),
    'delay': path.join(__dirname, 'commands', 'delay')
  },
  booleans: ['verbose', 'help'],
  options: ['name', 'message'],
  alias: {
    'v': 'verbose',
    'n': 'name'
  },
  help: path.join(__dirname, 'help', 'main.txt') // Path to a main help file
};

/* commands/default.js */
module.exports = function defaultCommand(args) {
  if (args.help) {
    return `Usage: my-cli [command] [--name <name>] [--message <message>] [--verbose]

Default command echoes arguments or shows a welcome message.
Try 'my-cli greet --name World' to greet someone.`;
  }
  if (args._.length > 0) {
    return `You ran the default command with arguments: ${args._.join(' ')}`;
  }
  return 'Welcome to the clite demo! Try `my-cli greet --name John`.';
};

/* commands/greet.js */
module.exports = function greetCommand(args) {
  const name = args.name || 'Stranger';
  const message = args.message || 'Hello';
  if (args.verbose) {
    return `Preparing to greet ${name} with message: "${message}"`;
  }
  return `${message}, ${name}!`;
};

/* commands/delay.js */
module.exports = function delayCommand(args) {
  const duration = parseInt(args._[0] || '1000', 10); // First argument is delay duration
  return new Promise(resolve => {
    setTimeout(() => resolve(`Delayed for ${duration}ms. All done!`), duration);
  });
};

/* help/main.txt */
// This is a simple help file for the 'my-cli' tool.
// Use 'my-cli --help' for general help.
// Use 'my-cli greet --help' for command specific help (if implemented).