{"id":17244,"library":"handle-cli-error","title":"CLI Error Handler","description":"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.","status":"active","version":"6.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/ehmicky/handle-cli-error","tags":["javascript","nodejs","shell","bash","cli","console","library","typescript"],"install":[{"cmd":"npm install handle-cli-error","lang":"bash","label":"npm"},{"cmd":"yarn add handle-cli-error","lang":"bash","label":"yarn"},{"cmd":"pnpm add handle-cli-error","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"handle-cli-error is an ES module and must be imported using `import` syntax. CommonJS `require` is not supported.","wrong":"const handleCliError = require('handle-cli-error')","symbol":"handleCliError","correct":"import handleCliError from 'handle-cli-error'"},{"note":"TypeScript users can import the `Options` type for strong typing of the configuration object.","symbol":"Options","correct":"import type { Options } from 'handle-cli-error'"},{"note":"The main function is exported as the default, but also as a named export for consistency with some bundlers or preferences.","wrong":"import * as handleCliError from 'handle-cli-error'","symbol":"handleCliError (named import)","correct":"import { handleCliError } from 'handle-cli-error'"}],"quickstart":{"code":"import handleCliError from 'handle-cli-error';\n\nconst main = async () => {\n  try {\n    // Simulate a CLI operation that might fail\n    const result = await Promise.resolve('some_data');\n    if (result !== 'expected_data') {\n      throw new Error('Unexpected data received. This is a critical error.', { cause: 'Data mismatch' });\n    }\n    console.log('CLI operation successful!');\n  } catch (error) {\n    handleCliError(error, {\n      classes: {\n        TypeError: { exitCode: 1, stack: false, props: false },\n        Error: { exitCode: 2, cause: true },\n        default: { exitCode: 3, colors: true, silent: process.env.NODE_ENV === 'test' },\n      },\n      header: 'CLI Error: {name}', // Custom header format\n      exitCode: 99, // Fallback exit code\n    });\n  }\n};\n\nmain();","lang":"typescript","description":"Demonstrates basic usage of `handleCliError` within a try-catch block, including error class-specific options and custom configuration for output."},"warnings":[{"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'`.","message":"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()`.","severity":"breaking","affected_versions":">=5.0.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.","message":"Minimal supported Node.js version is now `18.18.0`.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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}`; }`","message":"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.","severity":"gotcha","affected_versions":">=6.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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'`.","cause":"Attempting to `require()` an ES module (`handle-cli-error`) in a CommonJS context.","error":"ERR_REQUIRE_ESM"},{"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.","cause":"Incorrect module resolution, often due to CommonJS environment attempting to load an ESM-only package or a broken `node_modules` installation.","error":"Error: Cannot find module 'handle-cli-error'"},{"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`.","cause":"Attempting to call `handleCliError` after an incorrect CommonJS `require()` or a mistaken named import when the module provides a default export.","error":"TypeError: handleCliError is not a function"},{"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`.","cause":"Confusion or misuse of the `props` and `cause` options after the v6.0.0 breaking change where `cause` was introduced for nested errors.","error":"The 'cause' option cannot be combined with 'props' in this way. See documentation for breaking changes in v6.0.0."}],"ecosystem":"npm","meta_description":null}