{"id":16208463,"url":"https://github.com/ehmicky/handle-cli-error","last_synced_at":"2025-04-09T16:08:35.074Z","repository":{"id":49035153,"uuid":"517136986","full_name":"ehmicky/handle-cli-error","owner":"ehmicky","description":"💣 Error handler for CLI applications 💥","archived":false,"fork":false,"pushed_at":"2025-03-29T03:22:10.000Z","size":7819,"stargazers_count":28,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T16:08:15.092Z","etag":null,"topics":["bash","cli","console","error","error-handling","error-monitoring","errors","exit","exitcode","handler","javascript","library","message","monitoring","nodejs","shell","stack","terminal","timeout","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ehmicky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-23T18:37:56.000Z","updated_at":"2025-03-29T03:22:13.000Z","dependencies_parsed_at":"2024-04-22T20:37:03.342Z","dependency_job_id":"28c7272d-fc61-4195-a4ec-0971a743f7fb","html_url":"https://github.com/ehmicky/handle-cli-error","commit_stats":{"total_commits":414,"total_committers":2,"mean_commits":207.0,"dds":0.009661835748792313,"last_synced_commit":"923bdf90944ac355c9e5a8cb9348c441210f6afe"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fhandle-cli-error","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fhandle-cli-error/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fhandle-cli-error/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fhandle-cli-error/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehmicky","download_url":"https://codeload.github.com/ehmicky/handle-cli-error/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065285,"owners_count":21041871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","cli","console","error","error-handling","error-monitoring","errors","exit","exitcode","handler","javascript","library","message","monitoring","nodejs","shell","stack","terminal","timeout","typescript"],"created_at":"2024-10-10T10:17:07.322Z","updated_at":"2025-04-09T16:08:35.052Z","avatar_url":"https://github.com/ehmicky.png","language":"JavaScript","readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/ehmicky/design/main/handle-cli-error/handle-cli-error_dark.svg\"/\u003e\n  \u003cimg alt=\"handle-cli-error logo\" src=\"https://raw.githubusercontent.com/ehmicky/design/main/handle-cli-error/handle-cli-error.svg\" width=\"500\"/\u003e\n\u003c/picture\u003e\n\n[![Node](https://img.shields.io/badge/-Node.js-808080?logo=node.js\u0026colorA=404040\u0026logoColor=66cc33)](https://www.npmjs.com/package/handle-cli-error)\n[![TypeScript](https://img.shields.io/badge/-Typed-808080?logo=typescript\u0026colorA=404040\u0026logoColor=0096ff)](/src/main.d.ts)\n[![Codecov](https://img.shields.io/badge/-Tested%20100%25-808080?logo=codecov\u0026colorA=404040)](https://codecov.io/gh/ehmicky/handle-cli-error)\n[![Mastodon](https://img.shields.io/badge/-Mastodon-808080.svg?logo=mastodon\u0026colorA=404040\u0026logoColor=9590F9)](https://fosstodon.org/@ehmicky)\n[![Medium](https://img.shields.io/badge/-Medium-808080.svg?logo=medium\u0026colorA=404040)](https://medium.com/@ehmicky)\n\nError handler for CLI applications.\n\n# Features\n\n- 🖍️ Pretty [colors](#%EF%B8%8F-colors), [icons](#-icon) and [header](#-header)\n- 💣 [Error class-specific](#-classes) handling\n- 🚒 [Graceful exit](#-timeout)\n- ⛑️ [Normalize](https://github.com/ehmicky/normalize-exception) invalid errors\n- 🔕 Log verbosity: [message](#-silent), [stack](#-stack), [properties](#-props)\n- 🚨 Custom [exit code](#-exitcode)\n- 💥 Exception-safe\n\n# Screenshot\n\n\u003cimg alt=\"handle-cli-error screenshot\" src=\"docs/screenshot.png\" width=\"500\"/\u003e\n\n# Example\n\n## General\n\n```js\n#!/usr/bin/env node\nimport handleCliError from 'handle-cli-error'\n\nconst cliMain = () =\u003e {\n  try {\n    // ...\n  } catch (error) {\n    handleCliError(error) // Logs `error` then exit the process\n  }\n}\n\ncliMain()\n```\n\n## Error class-specific\n\n```js\nhandleCliError(error, {\n  classes: {\n    InputError: { exitCode: 1, stack: false },\n    DatabaseError: { exitCode: 2, stack: false },\n    default: { exitCode: 3 },\n  },\n})\n```\n\n# Install\n\n```bash\nnpm install handle-cli-error\n```\n\nThis package works in Node.js \u003e=18.18.0.\n\nThis is an ES module. It must be loaded using\n[an `import` or `import()` statement](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c),\nnot `require()`. If TypeScript is used, it must be configured to\n[output ES modules](https://www.typescriptlang.org/docs/handbook/esm-node.html),\nnot CommonJS.\n\n# API\n\n## handleCliError(error, options?)\n\n`error` `any`\\\n`options` [`Options?`](#options)\\\n_Return value_: `undefined`\n\nLogs `error` on the console (`stderr`) then exits the process.\n\nThis never throws. Invalid errors are silently\n[normalized](https://github.com/ehmicky/normalize-exception).\n\n### Options\n\n#### 🚨 exitCode\n\n_Type_: `integer`\\\n_Default_: `1`\n\nProcess [exit code](https://en.wikipedia.org/wiki/Exit_status).\n\nNote: when passing invalid [`options`](#options), the exit code is always `125`.\n\n#### 📕 stack\n\n_Type_: `boolean`\\\n_Default_: `true`\n\nWhether to log the error's stack trace.\n\n#### 📢 props\n\n_Type_: `boolean`\\\n_Default_: `true`\n\nWhether to log the error's additional properties.\n\n#### 🔕 silent\n\n_Type_: `boolean`\\\n_Default_: `false`\n\nExits the process without logging anything on the console.\n\n#### 🖍️ colors\n\n_Type_: `boolean`\\\n_Default_: `true` in terminals, `false` otherwise\n\nWhether to colorize the error's message, stack trace and additional properties.\n\nQuoted strings in the error's message are printed in bold (for `\"...\"` and\n`'...'`) and in italic (for `` `...` ``).\n\n#### ❌ icon\n\n_Type_: `string`\\\n_Default_: `'cross'`\n\nIcon prepended to the error's name. The available values are listed\n[here](https://github.com/sindresorhus/figures/blob/main/readme.md#figures-1).\nCan be disabled by passing an empty string.\n\n#### 💄 header\n\n_Type_: `string`\\\n_Default_: `'red bold'`\n\nColor/style of the error's [icon](#-icon) and name. The available values are\nlisted [here](https://github.com/ehmicky/chalk-string#available-styles). Several\nstyles can be specified by using spaces. Can be disabled by passing an empty\nstring.\n\n#### 🚒 timeout\n\n_Type_: `integer` (in milliseconds)\\\n_Default_: `5000` (5 seconds)\n\nThe process exits gracefully: it waits for any ongoing tasks (callbacks,\npromises, etc.) to complete, up to a specific `timeout`.\n\nSpecial values:\n\n- `0`: Exits right away, without waiting for ongoing tasks\n- `Number.POSITIVE_INFINITY`: Waits for ongoing tasks forever, without timing\n  out\n\n#### 💣 classes\n\n_Type_: `object`\\\n_Default_: `{}`\n\nSpecify [different options per error class](#error-class-specific). The object:\n\n- Keys are either the\n  [`error.name`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/name),\n  or `\"default\"` (used if no `error.name` matches)\n- Values are [options](#options) objects\n\n# Related projects\n\n- [`modern-errors`](https://github.com/ehmicky/modern-errors): Handle errors in\n  a simple, stable, consistent way\n- [`modern-errors-cli`](https://github.com/ehmicky/modern-errors-cli): Handle\n  errors in CLI modules\n- [`error-custom-class`](https://github.com/ehmicky/error-custom-class): Create\n  one error class\n- [`error-class-utils`](https://github.com/ehmicky/error-class-utils): Utilities\n  to properly create error classes\n- [`error-serializer`](https://github.com/ehmicky/error-serializer): Convert\n  errors to/from plain objects\n- [`normalize-exception`](https://github.com/ehmicky/normalize-exception):\n  Normalize exceptions/errors\n- [`is-error-instance`](https://github.com/ehmicky/is-error-instance): Check if\n  a value is an `Error` instance\n- [`merge-error-cause`](https://github.com/ehmicky/merge-error-cause): Merge an\n  error with its `cause`\n- [`set-error-class`](https://github.com/ehmicky/set-error-class): Properly\n  update an error's class\n- [`set-error-message`](https://github.com/ehmicky/set-error-message): Properly\n  update an error's message\n- [`wrap-error-message`](https://github.com/ehmicky/wrap-error-message):\n  Properly wrap an error's message\n- [`set-error-props`](https://github.com/ehmicky/set-error-props): Properly\n  update an error's properties\n- [`set-error-stack`](https://github.com/ehmicky/set-error-stack): Properly\n  update an error's stack\n- [`error-cause-polyfill`](https://github.com/ehmicky/error-cause-polyfill):\n  Polyfill `error.cause`\n- [`log-process-errors`](https://github.com/ehmicky/log-process-errors): Show\n  some ❤ to Node.js process errors\n- [`error-http-response`](https://github.com/ehmicky/error-http-response):\n  Create HTTP error responses\n- [`winston-error-format`](https://github.com/ehmicky/winston-error-format): Log\n  errors with Winston\n\n# Credits\n\nThe logo background was created by\n[dgim-studio](https://www.freepik.com/free-vector/comic-dynamic-elements-set_7997347.htm).\n\n# Support\n\nFor any question, _don't hesitate_ to [submit an issue on GitHub](../../issues).\n\nEveryone is welcome regardless of personal background. We enforce a\n[Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and\ninclusive environment.\n\n# Contributing\n\nThis project was made with ❤️. The simplest way to give back is by starring and\nsharing it online.\n\nIf the documentation is unclear or has a typo, please click on the page's `Edit`\nbutton (pencil icon) and suggest a correction.\n\nIf you would like to help us fix a bug or add a new feature, please check our\n[guidelines](CONTRIBUTING.md). Pull requests are welcome!\n\n\u003c!-- Thanks go to our wonderful contributors: --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START --\u003e\n\u003c!-- prettier-ignore --\u003e\n\u003c!--\n\u003ctable\u003e\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://fosstodon.org/@ehmicky\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/8136211?v=4\" width=\"100px;\" alt=\"ehmicky\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eehmicky\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ehmicky/handle-cli-error/commits?author=ehmicky\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#design-ehmicky\" title=\"Design\"\u003e🎨\u003c/a\u003e \u003ca href=\"#ideas-ehmicky\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"https://github.com/ehmicky/handle-cli-error/commits?author=ehmicky\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fhandle-cli-error","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehmicky%2Fhandle-cli-error","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fhandle-cli-error/lists"}