CLI Error Handler

6.2.0 · active · verified Wed Apr 22

handle-cli-error is a robust error handling library specifically designed for Node.js command-line interface (CLI) applications. It provides a comprehensive solution for displaying errors to users in a clear, consistent, and visually appealing manner, then gracefully exiting the process. The current stable version is 6.2.0, with frequent minor releases introducing new features and improvements, such as enhanced customization options. Key differentiators include its ability to generate pretty, colorized error output with icons and headers, support for error class-specific handling (allowing different exit codes or logging behaviors per error type), graceful process exit with customizable timeouts, and automatic normalization of invalid Error objects using `normalize-exception`. It also allows fine-grained control over what error details are logged, such as stack traces, nested error causes, and additional error properties, making it highly configurable for various CLI needs.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` an ES module (`handle-cli-error`) in a CommonJS context.

fix Migrate your file to ES modules by changing its extension to `.mjs` or by adding `"type": "module"` to your `package.json`. Then, use `import handleCliError from 'handle-cli-error'`.
```
Error: Cannot find module 'handle-cli-error'
```
cause Incorrect module resolution, often due to CommonJS environment attempting to load an ESM-only package or a broken `node_modules` installation.

fix First, ensure `npm install handle-cli-error` ran successfully. If your project is CommonJS, review the `ERR_REQUIRE_ESM` warning. Also, try deleting `node_modules` and `package-lock.json`, then reinstalling dependencies.
```
TypeError: handleCliError is not a function
```
cause Attempting to call `handleCliError` after an incorrect CommonJS `require()` or a mistaken named import when the module provides a default export.

fix Ensure you are using the correct ESM default import: `import handleCliError from 'handle-cli-error'`. If using TypeScript, check your `tsconfig.json` for `"module": "Node16"` or `"NodeNext"` and `"esModuleInterop": true`.
```
The 'cause' option cannot be combined with 'props' in this way. See documentation for breaking changes in v6.0.0.
```
cause Confusion or misuse of the `props` and `cause` options after the v6.0.0 breaking change where `cause` was introduced for nested errors.

fix The `props` option now controls only additional error properties, while `cause` controls nested errors (`error.cause` and `error.errors`). Set `cause: false` to hide nested errors, not `props: false`.

Warnings

breaking The package `handle-cli-error` is an ES module (ESM) only since version 5.0.0. It must be imported using `import` statements and cannot be loaded with CommonJS `require()`.
Fix: Ensure your project is configured for ESM, typically by setting `"type": "module"` in your `package.json` or by using `.mjs` file extensions. Replace all `require('handle-cli-error')` with `import handleCliError from 'handle-cli-error'`.
breaking Minimal supported Node.js version is now `18.18.0`.
Fix: Upgrade your Node.js runtime to version `18.18.0` or newer. If you are on an older Node.js version, you will need to stick to `handle-cli-error` v4.x.
breaking In v6.0.0, the `props` option no longer controls the printing of nested errors (`error.cause` and `error.errors`). A new dedicated `cause` option was introduced for this purpose.
Fix: If you previously relied on `props: false` to hide nested errors, you must now explicitly set `cause: false` instead. The `props` option now strictly controls additional error properties, not nested errors.
gotcha When customizing error output with `error.beautiful(output)` (since v6.1.0) or the `custom` option (since v6.2.0), ensure your method returns a string. Returning `undefined` or a non-string value may lead to unexpected output or errors.
Fix: Always return a string from your `beautiful` method or the function specified by the `custom` option. For example: `class MyError extends Error { beautiful = (output) => `Customized: ${output}`; }`

Install

npm install handle-cli-error npm
yarn add handle-cli-error yarn
pnpm add handle-cli-error pnpm

Imports

handleCliError
wrong:
```
const handleCliError = require('handle-cli-error')
```
correct:
```
import handleCliError from 'handle-cli-error'
```
handle-cli-error is an ES module and must be imported using `import` syntax. CommonJS `require` is not supported.
Options
```
import type { Options } from 'handle-cli-error'
```
TypeScript users can import the `Options` type for strong typing of the configuration object.
handleCliError (named import)
wrong:
```
import * as handleCliError from 'handle-cli-error'
```
correct:
```
import { handleCliError } from 'handle-cli-error'
```
The main function is exported as the default, but also as a named export for consistency with some bundlers or preferences.

Quickstart

Demonstrates basic usage of `handleCliError` within a try-catch block, including error class-specific options and custom configuration for output.

import handleCliError from 'handle-cli-error';

const main = async () => {
  try {
    // Simulate a CLI operation that might fail
    const result = await Promise.resolve('some_data');
    if (result !== 'expected_data') {
      throw new Error('Unexpected data received. This is a critical error.', { cause: 'Data mismatch' });
    }
    console.log('CLI operation successful!');
  } catch (error) {
    handleCliError(error, {
      classes: {
        TypeError: { exitCode: 1, stack: false, props: false },
        Error: { exitCode: 2, cause: true },
        default: { exitCode: 3, colors: true, silent: process.env.NODE_ENV === 'test' },
      },
      header: 'CLI Error: {name}', // Custom header format
      exitCode: 99, // Fallback exit code
    });
  }
};

main();

view raw JSON →