{"id":14263228,"url":"https://github.com/thenativeweb/buntstift","last_synced_at":"2025-08-13T09:32:41.385Z","repository":{"id":26454463,"uuid":"29905655","full_name":"thenativeweb/buntstift","owner":"thenativeweb","description":"buntstift makes the CLI colorful.","archived":false,"fork":false,"pushed_at":"2024-06-16T09:52:18.000Z","size":2591,"stargazers_count":28,"open_issues_count":2,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-07-18T22:15:49.675Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/thenativeweb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-27T08:57:07.000Z","updated_at":"2024-02-14T15:18:11.000Z","dependencies_parsed_at":"2024-06-18T18:13:05.839Z","dependency_job_id":"f2f73759-3760-441d-b1b7-5da47a2ded68","html_url":"https://github.com/thenativeweb/buntstift","commit_stats":{"total_commits":496,"total_committers":8,"mean_commits":62.0,"dds":"0.41532258064516125","last_synced_commit":"b0229870ff284f084dae003f84dfb94b3ae5a75b"},"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenativeweb%2Fbuntstift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenativeweb%2Fbuntstift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenativeweb%2Fbuntstift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenativeweb%2Fbuntstift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thenativeweb","download_url":"https://codeload.github.com/thenativeweb/buntstift/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":215927924,"owners_count":15950276,"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":[],"created_at":"2024-08-22T13:04:46.245Z","updated_at":"2024-08-22T13:06:34.533Z","avatar_url":"https://github.com/thenativeweb.png","language":"TypeScript","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"# buntstift\n\nbuntstift makes the CLI colorful.\n\n![buntstift](https://github.com/thenativeweb/buntstift/raw/main/images/logo.jpg \"buntstift\")\n\n## Status\n\n| Category         | Status                                                                                                 |\n| ---------------- | ------------------------------------------------------------------------------------------------------ |\n| Version          | [![npm](https://img.shields.io/npm/v/buntstift)](https://www.npmjs.com/package/buntstift)              |\n| Dependencies     | ![David](https://img.shields.io/david/thenativeweb/buntstift)                                          |\n| Dev dependencies | ![David](https://img.shields.io/david/dev/thenativeweb/buntstift)                                      |\n| Build            | ![GitHub Actions](https://github.com/thenativeweb/buntstift/workflows/Release/badge.svg?branch=main) |\n| License          | ![GitHub](https://img.shields.io/github/license/thenativeweb/buntstift)                                |\n\n## Installation\n\n```shell\n$ npm install buntstift\n```\n\n## Quick start\n\nFirst you need to integrate buntstift into your application:\n\n```javascript\nconst { buntstift } = require('buntstift');\n```\n\nIf you use TypeScript, use the following code instead:\n\n```typescript\nimport { buntstift } from 'buntstift';\n```\n\nTo show messages in the terminal, use the `info` function:\n\n```javascript\nbuntstift.info('Server started on port 3000.');\n```\n\nIf you need to highlight messages, use `success`, `error`, and `warn` instead of `info`:\n\n```javascript\nbuntstift.success('Server started on port 3000.');\nbuntstift.error('Failed to start server.');\nbuntstift.warn('Server started, but without IPv6 support.');\n```\n\nFinally, there is also `verbose` to show messages meant for debugging or analysing application flow. Please note that by default, these messages are not shown in the terminal, unless you explicitly enable verbose mode:\n\n```javascript\nbuntstift.verbose('Verifying whether port 3000 is available...');\n```\n\nTo show messages on the terminal without any support from buntstift, e.g. to pass through some already preformatted output, use the `raw` function:\n\n```javascript\nconst preformattedOutput = // ...\n\nbuntstift.raw(preformattedOutput);\n```\n\nBy default, `raw` writes to the application's standard output stream. Sometimes you want the message to go to the standard error stream instead. For that, provide an options object and specify `stderr` as the target:\n\n```javascript\nbuntstift.raw(preformattedOutput, { target: 'stderr' });\n```\n\n### Prefixing messages\n\nExcept `raw`, all the aforementioned functions are able to show a prefix before the actual message, and some of them do so by default. To explicitly set a prefix, provide an options object and set its `prefix` property to the desired value:\n\n```javascript\nbuntstift.success('Server started on port 3000.', { prefix: 'OK' });\n// =\u003e OK Server started on port 3000.\n```\n\n### Configuring buntstift\n\nWithout any manual configuration, buntstift tries to use reasonable defaults. However, sometimes you may need to change its configuration. For that, first use the `getConfiguration` function to get the current configuration:\n\n```javascript\nconst configuration = buntstift.getConfiguration();\n```\n\nThe configuration object now has a number of functions (see section below) to adjust the configuration. E.g., to disable colors, call the `withColorLevel` function and hand over `ColorLevel.Disabled` as parameter:\n\n```javascript\nconst updatedConfiguration = configuration.withColorLevel(ColorLevel.Disabled);\n```\n\n*Please note that all of the functions on the configuration object do not mutate the configuration, but return a new instance instead!*\n\nFinally, set the new configuration using the `configure` function. Typically, because of the configuration object's immutability, you may want to do all of this in a single statement:\n\n```javascript\nbuntstift.configure(\n  buntstift.getConfiguration().\n    withColorLevel(ColorLevel.Disabled).\n    withUtf8(false)\n);\n```\n\n#### Setting the colors level\n\nBy default, buntstift uses colors to show its messages. To explicitly disable colors or set a specific color level, use the `withColorLevel` function:\n\n```javascript\nconst updatedConfiguration = configuration.withColorLevel(ColorLevel.Disabled);\nconst updatedConfiguration = configuration.withColorLevel(ColorLevel.Ansi);\n```\n\nSee the [`ColorLevel`](./lib/ColorLevel.ts) enum for all possible values.\n\n#### Enabling or disabling interactive sessions\n\nIn interactive sessions the spinner is shown in the terminal, while in non-interactive sessions it is hidden. By default, buntstift tries to detect whether a session is interative or not. To explicitly enable or disable interactive sessions, use the `withInteractiveSession` function:\n\n```javascript\nconst updatedConfiguration = configuration.withInteractiveSession(true);\n```\n\n#### Enabling or disabling quiet mode\n\nIn quiet mode no messages are written to the terminal any more, except messages written using `error`, `warn`, and `raw`. By default, the quiet mode is disabled. To enable or disable quiet mode, use the `withQuietMode` function:\n\n```javascript\nconst updatedConfiguration = configuration.withQuietMode(true);\n```\n\n#### Enabling or disabling UTF8\n\nBy default, buntstift uses some UTF8 instead of simple ASCII characters. To enable or disable UTF8, use the `withUtf8` function:\n\n```javascript\nconst updatedConfiguration = configuration.withUtf8(true);\n```\n\n#### Enabling or disabling verbose mode\n\nIn verbose mode, messages written using `verbose` are shown in the terminal, while in non-verbose mode, they are silently skipped. To enable or disable verbose mode, use the `withVerboseMode` function:\n\n```javascript\nconst updatedConfiguration = configuration.withVerboseMode(true);\n```\n\n### Configuring individual messages\n\nFrom time to time, you may want to change the configuration, but limit the effect of these changes to individual messages. For that, you can pass configuration options when calling buntstift functions. E.g., to disable UTF8 for a single message, use the following code:\n\n```javascript\nbuntstift.success('Server started on port 3000.', { isUtf8Enabled: false });\n```\n\nYou may also pass the properties `isColorEnabled`, `isInteractiveSession`, `isQuietModeEnabled`, and `isVerboseModeEnabled`.\n\n### Using lines\n\nTo show a line, e.g. to separate two sections, use the `line` function:\n\n```javascript\nbuntstift.line();\n```\n\n### Using headers\n\nTo show a header, e.g. to denote the start of a new section, use the `header` function:\n\n```javascript\nbuntstift.header('Running tests...');\n```\n\nYou may change the header's prefix using the `prefix` property mentioned above.\n\n### Using empty lines\n\nTo show an empty line, use the `newLine` function:\n\n```javascript\nbuntstift.newLine();\n```\n\n## Using lists\n\nTo show a list in the terminal use `list` and provide a list item. Optionally, you may specify an indentation level. Setting the indentation level to `0` is equal to omitting it:\n\n```javascript\nbuntstift.list('foo');\nbuntstift.list('bar');\nbuntstift.list('baz', { level: 1 });\n\n// =\u003e ∙ foo\n//    ∙ bar\n//      ∙ baz\n```\n\nYou may change the list item's bullet using the `prefix` property mentioned above.\n\n### Using tables\n\nFrom time to time you need to show tabular data in the terminal. For that, use `table` and provide an array of objects to use as rows. The objects all must have the very same properties, i.e. they must match the same interface.\n\nThe keys of the row objects are rendered as table header in a human-readable way. The individual cells become padded automatically. Numbers are aligned to the right, anything else is aligned to the left:\n\n```javascript\nbuntstift.table([\n  [{ protocol: 'http', port: 80 }],\n  [{ protocol: 'https', port: 443 }]\n]);\n\n// =\u003e Protocol  Port\n//    ────────  ────\n//    http        80\n//    https      443\n```\n\nIf you don't want to show the header, additionally provide an options object and set its `showHeader` property to `false`:\n\n```javascript\nbuntstift.table([\n  [{ protocol: 'http', port: 80 }],\n  [{ protocol: 'https', port: 443 }]\n], { showHeader: false });\n\n// =\u003e http    80\n//    https  443\n```\n\n### Waiting for long-running tasks\n\nIf your application performs a long-running task, you may want to show a spinner in the terminal. For that, call the `wait` function, which returns another function to stop the spinner at a later point in time. If you use any buntstift function while the spinner is active, buntstift will take care of disabling and re-enabling the spinner as needed, to avoid flickering:\n\n```javascript\nconst stop = buntstift.wait();\n\n// ...\n\nstop();\n```\n\n*Please note that the spinner is written to the application's standard error stream, not to the standard output stream.*\n\n### Getting user input\n\nBesides the various ways to display information, buntstift is also able to get input from the user. For that, use the `ask`, `confirm` and `select` functions.\n\n#### Asking a question\n\nIf you want to ask the user a question, use `ask` and provide a `question`:\n\n```javascript\nconst answer = await buntstift.ask('What do you want to do today?');\n```\n\nOptionally, you may specify a regular expression to use as a mask to match the answer against:\n\n```javascript\nconst answer = await buntstift.ask('What do you want to do today?', /.+/g);\n```\n\nAlternatively, you may specify a default value for the answer:\n\n```javascript\nconst answer = await buntstift.ask('What do you want to do today?', 'coding');\n```\n\nIf you want to provide both, i.e. a mask and a default value, provide an options object:\n\n```javascript\nconst answer = await buntstift.ask('What do you want to do today?', {\n  mask: /.+/g,\n  default: 'coding'\n});\n```\n\nTo ask for a password, provide an options object and set the `echo` property to `false`:\n\n```javascript\nconst password = await buntstift.ask('Please enter your password:', {\n  echo: false\n});\n```\n\n#### Getting a confirmation\n\nIf you want to get a conformation from the user, use `confirm` and provide a `question`:\n\n```javascript\nconst isSure = await buntstift.confirm('Are you sure?');\n```\n\nUnless specified otherwise, the default answer is `true`. To change this, provide `false` as second parameter:\n\n```javascript\nconst isSure = await buntstift.confirm('Are you sure?', false);\n```\n\n#### Selecting from a list\n\nIf you want the user to select a value from a list, use `select` and provide a `question` as well as a selection of choices:\n\n```javascript\nconst favoriteColor = await buntstift.select('What is your favorite color?', [\n  'red',\n  'green',\n  'blue'\n]);\n```\n\n### Chaining functions\n\nIf you want to run a number of buntstift functions as a sequence, you can chain them into a single call (as long as you limit yourself to the synchronous functions):\n\n```javascript\ntry {\n  // ...\n} catch (ex) {\n  buntstift.\n    error('An unexpected error occured.').\n    info(ex.message).\n    verbose(ex.stack);\n}\n```\n\n## Running quality assurance\n\nTo run quality assurance for this module use [roboter](https://www.npmjs.com/package/roboter):\n\n```shell\n$ npx roboter\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthenativeweb%2Fbuntstift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthenativeweb%2Fbuntstift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthenativeweb%2Fbuntstift/lists"}