CLI Utilities Toolkit

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ...cli-util' from ... not supported.

  cause Attempting to import `cli-util` using ES module `import` syntax in a JavaScript module when `cli-util` is a CommonJS module.
  fix Change the import statement to CommonJS `require()` syntax: `const cli = require('cli-util');`

• TypeError: "some string".green is not a function

  cause The `colors` library, which adds color methods to `String.prototype`, was not loaded or `cli-util` (which loads `colors`) was not required.
  fix Ensure `const cli = require('cli-util');` is called at least once in your application's lifecycle before attempting to use string color methods. Note that this package is abandoned, and `colors` modifies `String.prototype`.

Warnings

• breaking The package is abandoned since 2014 and is not maintained. It relies on extremely old versions of dependencies (e.g., `colors@0.6.2`, `commander@2.0.0`, `docopt@0.6.0`) that have known security vulnerabilities, outdated APIs, or adverse side effects (like `colors` modifying `String.prototype`). Using this package in modern applications is highly discouraged and poses security risks and compatibility issues.
  Fix: Migrate to actively maintained CLI utility libraries such as `commander.js` (latest), `yargs`, `chalk`, `ora`, or `enquirer` for modern CLI development.
• gotcha The `colors` dependency (version 0.6.2) included in this package modifies the global `String.prototype`. This means methods like `.red`, `.green`, `.yellow`, etc., become available on all string objects globally after `cli-util` is required. This can lead to unexpected behavior, conflicts with other libraries, or make code harder to reason about due to global state modification.
  Fix: Avoid using this package. If absolutely necessary, be aware of the global `String.prototype` modifications and test thoroughly for conflicts. Consider encapsulating its usage if possible.
• gotcha This package is strictly CommonJS (CJS) and does not provide ES module (ESM) exports. Attempting to `import` it in an ESM context will result in a runtime error.
  Fix: If used in an ESM project, you must use `require()` to import it, typically by wrapping it or adjusting your build setup for CJS compatibility. For example: `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const cli = require('cli-util');` However, given the 'abandoned' status, migrating away is the recommended fix.
• deprecated The `commander` (version 2.0.0) and `docopt` (version 0.6.0) dependencies are severely outdated. Their APIs have changed significantly over many major versions since then, and they lack modern features, bug fixes, and security patches. Code relying on these old APIs will be incompatible with newer versions and potentially insecure.
  Fix: Upgrade to current, actively maintained CLI argument parsing libraries like the latest `commander.js` or `yargs`. This will require a complete rewrite of the argument parsing logic.

Install

• npm install cli-util npm
• yarn add cli-util yarn
• pnpm add cli-util pnpm

Imports

• log
  wrong:

  import { log } from 'cli-util';

  correct:

  const cli = require('cli-util');
  cli.log('message');

  The package is CommonJS-only and does not support ES modules directly. Functions are accessed via the main export object.
• colors
  wrong:

  import colors from 'colors';

  correct:

  const cli = require('cli-util');
  cli.log('Hello'.green); // Uses String.prototype modification from the internal 'colors' dependency

  The 'colors' library is an internal dependency (v0.6.2) that modifies String.prototype, making methods like `.green` available on strings after the `cli-util` module is required. It's not directly exposed for import.
• header
  wrong:

  const { header } = require('cli-util'); // While technically correct, it's more idiomatic for CJS to assign the entire module.exports object.

  correct:

  const cli = require('cli-util');
  cli.header('My CLI Tool', { indent: 2 });

  All utility functions are properties of the main module export.

Quickstart

Demonstrates basic usage of cli-util for logging, styling output with colors, displaying headers, and formatting text in columns and with padding.

const cli = require('cli-util');

// Logging with colors (due to internal 'colors' dependency modifying String.prototype)
cli.log('Starting CLI application...'.green);
cli.warn('A warning message.'.yellow);
cli.error('An error occurred!'.red);

// Displaying a header
cli.header('CLI-Util Example', { indent: 1 });

// Formatting lines and columns
const data = [
  ['Name:', 'John Doe'],
  ['Email:', 'john.doe@example.com'],
  ['Status:', 'Active']
];
cli.lines(data.map(row => cli.pad(row[0], 10) + row[1]));

console.log(cli.line()); // Prints a separator line

// Example of padding
const paddedText = cli.rightPad('Hello', 15, '.');
cli.log(`Padded text: ${paddedText}`);

cli.ok('Application finished successfully.'.blue);