{"id":13526817,"url":"https://github.com/npkgz/cli-progress","last_synced_at":"2025-05-14T01:09:42.469Z","repository":{"id":38267912,"uuid":"47921134","full_name":"npkgz/cli-progress","owner":"npkgz","description":" :hourglass: easy to use progress-bar for command-line/terminal applications","archived":false,"fork":false,"pushed_at":"2023-10-23T16:58:31.000Z","size":368,"stargazers_count":1110,"open_issues_count":21,"forks_count":84,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-29T15:01:10.704Z","etag":null,"topics":["cli","command-line","command-line-interface","command-line-tool","javascript","nodejs","nodejs-library","progress-bar","progressbar"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/cli-progress","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/npkgz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"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":"2015-12-13T13:52:36.000Z","updated_at":"2024-10-29T02:56:16.000Z","dependencies_parsed_at":"2024-06-18T11:14:20.871Z","dependency_job_id":"f8160539-474d-410f-b50a-6cff8adaa845","html_url":"https://github.com/npkgz/cli-progress","commit_stats":{"total_commits":125,"total_committers":19,"mean_commits":6.578947368421052,"dds":0.24,"last_synced_commit":"e2347a35a6c0922cfb0a077cf5ed21696fba46da"},"previous_names":["andidittrich/node.cli-progress"],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fcli-progress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fcli-progress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fcli-progress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fcli-progress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npkgz","download_url":"https://codeload.github.com/npkgz/cli-progress/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248229980,"owners_count":21069020,"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":["cli","command-line","command-line-interface","command-line-tool","javascript","nodejs","nodejs-library","progress-bar","progressbar"],"created_at":"2024-08-01T06:01:35.440Z","updated_at":"2025-04-10T13:56:26.673Z","avatar_url":"https://github.com/npkgz.png","language":"JavaScript","readme":"[![Build Status](https://travis-ci.org/npkgz/cli-progress.svg?branch=master)](https://travis-ci.org/npkgz/cli-progress)\n\n[Single Bar](#single-bar-mode) | [Multi Bar](#multi-bar-mode) | [Options](#options-1) | [Examples](examples/) | [Presets](presets/) | [Events](docs/events.md)\n\nCLI-Progress\n============\neasy to use progress-bar for command-line/terminal applications\n\n![Demo](assets/cli-progress.gif)\n\n![Demo](assets/presets.png)\n\nInstall\n--------\n\n```bash\n$ yarn add cli-progress\n$ npm install cli-progress --save\n```\n\nFeatures\n--------\n\n* **Simple**, **Robust** and **Easy** to use\n* Full customizable output format (various placeholders are available)\n* Single progressbar mode\n* Multi progessbar mode\n* Custom Bar Characters\n* FPS limiter\n* ETA calculation based on elapsed time\n* Custom Tokens to display additional data (payload) within the bar\n* TTY and NOTTY mode\n* No callbacks required - designed as pure, external controlled UI widget\n* Works in Asynchronous and Synchronous tasks\n* Preset/Theme support\n* Custom bar formatters (via callback)\n* Logging during multibar operation\n\nUsage\n------------\n\nMultiple examples are available e.g. [example.js](https://github.com/npkgz/cli-progress/blob/master/examples/example.js) - just try it `$ node example.js`\n\n```js\nconst cliProgress = require('cli-progress');\n\n// create a new progress bar instance and use shades_classic theme\nconst bar1 = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);\n\n// start the progress bar with a total value of 200 and start value of 0\nbar1.start(200, 0);\n\n// update the current value in your application..\nbar1.update(100);\n\n// stop the progress bar\nbar1.stop();\n```\n\nSingle Bar Mode\n-----------------------------------\n\n![Demo](assets/presets.png)\n\n### Example ###\n\n```js\nconst cliProgress = require('cli-progress');\n\n// note: you have to install this dependency manually since it's not required by cli-progress\nconst colors = require('ansi-colors');\n\n// create new progress bar\nconst b1 = new cliProgress.SingleBar({\n    format: 'CLI Progress |' + colors.cyan('{bar}') + '| {percentage}% || {value}/{total} Chunks || Speed: {speed}',\n    barCompleteChar: '\\u2588',\n    barIncompleteChar: '\\u2591',\n    hideCursor: true\n});\n\n// initialize the bar - defining payload token \"speed\" with the default value \"N/A\"\nb1.start(200, 0, {\n    speed: \"N/A\"\n});\n\n// update values\nb1.increment();\nb1.update(20);\n\n// stop the bar\nb1.stop();\n```\n\n### Constructor ###\n\nInitialize a new Progress bar. An instance can be used **multiple** times! it's not required to re-create it!\n\n```js\nconst cliProgress = require('cli-progress');\n\nconst \u003cinstance\u003e = new cliProgress.SingleBar(options:object [, preset:object]);\n```\n\n#### Options ####\n\n\n### ::start() ###\n\nStarts the progress bar and set the total and initial value\n\n```js\n\u003cinstance\u003e.start(totalValue:int, startValue:int [, payload:object = {}]);\n```\n\n### ::update() ###\n\nSets the current progress value and optionally the payload with values of custom tokens as a second parameter. To update payload only, set currentValue to `null`.\n\n```js\n\u003cinstance\u003e.update([currentValue:int [, payload:object = {}]]);\n\n// update progress without altering value\n\u003cinstance\u003e.update([payload:object = {}]);\n```\n\n### ::increment() ###\n\nIncreases the current progress value by a specified amount (default +1). Update payload optionally\n\n```js\n\u003cinstance\u003e.increment([delta:int [, payload:object = {}]]);\n\n// delta=1 assumed\n\u003cinstance\u003e.increment(payload:object = {}]);\n```\n\n### ::setTotal() ###\n\nSets the total progress value while progressbar is active. Especially useful handling dynamic tasks.\n\n```js\n\u003cinstance\u003e.setTotal(totalValue:int);\n```\n\n### ::stop() ###\n\nStops the progress bar and go to next line\n\n```js\n\u003cinstance\u003e.stop();\n```\n\n### ::updateETA() ###\n\nForce eta calculation update (long running processes) without altering the progress values.\n\nNote: you may want to increase `etaBuffer` size - otherwise it can cause `INF` eta values in case the value didn't changed within the time series.\n\n```js\n\u003cinstance\u003e.updateETA();\n```\n\n\nMulti Bar Mode\n-----------------------------------\n\n![Demo](assets/multibar.png)\n\n### Example ###\n\n```js\nconst cliProgress = require('cli-progress');\n\n// create new container\nconst multibar = new cliProgress.MultiBar({\n    clearOnComplete: false,\n    hideCursor: true,\n    format: ' {bar} | {filename} | {value}/{total}',\n}, cliProgress.Presets.shades_grey);\n\n// add bars\nconst b1 = multibar.create(200, 0);\nconst b2 = multibar.create(1000, 0);\n\n// control bars\nb1.increment();\nb2.update(20, {filename: \"test1.txt\"});\nb1.update(20, {filename: \"helloworld.txt\"});\n\n// stop all bars\nmultibar.stop();\n```\n\n### Constructor ###\n\nInitialize a new multiprogress container. Bars need to be added. The options/presets are used for each single bar!\n\n```js\nconst cliProgress = require('cli-progress');\n\nconst \u003cinstance\u003e = new cliProgress.MultiBar(options:object [, preset:object]);\n```\n\n### ::create() ###\n\nAdds a new progress bar to the container and starts the bar. Returns regular `SingleBar` object which can be individually controlled.\n\nAdditional `barOptions` can be passed directly to the [generic-bar](lib/generic-bar.js) to override the global options for a single bar instance. This can be useful to change the appearance of a single bar object. But be patient: this should only be used to override formats - DON'T try to set other global options like the terminal, synchronous flags, etc..\n\n```js\nconst \u003cbarInstance\u003e = \u003cinstance\u003e.create(totalValue:int, startValue:int [, payload:object = {} [, barOptions:object = {}]]);\n```\n\n### ::remove() ###\n\nRemoves an existing bar from the multi progress container.\n\n```js\n\u003cinstance\u003e.remove(\u003cbarInstance\u003e:object);\n```\n\n### ::stop() ###\n\nStops the all progress bars\n\n```js\n\u003cinstance\u003e.stop();\n```\n\n### ::log() ###\n\nOutputs (buffered) content on top of the multibars during operation. \n\n**Notice: newline at the end is required**\n\nExample: [example-logging.js](examples/example-logging.js)\n\n```js\n\u003cinstance\u003e.log(\"Hello World\\n\");\n```\n\nOptions\n-----------------------------------\n\nThe following options can be changed\n\n- `format` (type:string|function) - progress bar output format @see format section\n- `fps` (type:float) - the maximum update rate (default: 10)\n- `stream` (type:stream) - output stream to use (default: `process.stderr`)\n- `stopOnComplete` (type:boolean) - automatically call `stop()` when the value reaches the total (default: false)\n- `clearOnComplete` (type:boolean) - clear the progress bar on complete / `stop()` call (default: false)\n- `barsize` (type:int) - the length of the progress bar in chars (default: 40)\n- `align` (type:char) - position of the progress bar - 'left' (default), 'right' or 'center'\n- `barCompleteChar` (type:char) - character to use as \"complete\" indicator in the bar (default: \"=\")\n- `barIncompleteChar` (type:char) - character to use as \"incomplete\" indicator in the bar (default: \"-\")\n- `hideCursor` (type:boolean) - hide the cursor during progress operation; restored on complete (default: false) - pass `null` to keep terminal settings\n- `linewrap` (type:boolean) - disable line wrapping (default: false) - pass `null` to keep terminal settings; pass `true` to add linebreaks automatically (not recommended)\n- `gracefulExit` (type:boolean) - stop the bars in case of `SIGINT` or `SIGTERM` - this restores most cursor settings before exiting (default: `false` - subjected to change)\n- `etaBuffer` (type:int) - number of updates with which to calculate the eta; higher numbers give a more stable eta (default: 10)\n- `etaAsynchronousUpdate` (type:boolean) - trigger an eta calculation update during asynchronous rendering trigger using the current value - should only be used for long running processes in conjunction with lof `fps` values and large `etaBuffer` (default: false)\n- `progressCalculationRelative` (type:boolean) - progress calculation uses `startValue` as zero-offset (default: false)\n- `synchronousUpdate` (type:boolean) - trigger redraw during `update()` in case threshold time x2 is exceeded (default: true) - limited to single bar usage\n- `noTTYOutput` (type:boolean) - enable scheduled output to notty streams - e.g. redirect to files (default: false)\n- `notTTYSchedule` (type:int) - set the output schedule/interval for notty output in `ms` (default: 2000ms)\n- `emptyOnZero` (type:boolean) - display progress bars with 'total' of zero(0) as empty, not full (default: false)\n- `forceRedraw` (type:boolean) - trigger redraw on every frame even if progress remains the same; can be useful if progress bar gets overwritten by other concurrent writes to the terminal (default: false)\n- `barGlue` (type:string) - a \"glue\" string between the complete and incomplete bar elements used to insert ascii control sequences for colorization (default: empty) - Note: in case you add visible \"glue\" characters the barsize will be increased by the length of the glue!\n- `autopadding` (type: boolean) - add padding chars to formatted time and percentage to force fixed width (default: false) - Note: handled standard format functions!\n- `autopaddingChar` (type: string) - the character sequence used for autopadding (default: \"   \") - Note: due to performance optimizations this value requires a length of 3 identical chars\n- `formatBar` (type: function) - a custom bar formatter function which renders the bar-element (default: [format-bar.js](lib/format-bar.js))\n- `formatTime` (type: function) - a custom timer formatter function which renders the formatted time elements like `eta_formatted` and `duration-formatted` (default: [format-time.js](lib/format-time.js))\n- `formatValue` (type: function) - a custom value formatter function which renders all other values (default: [format-value.js](lib/format-value.js))\n\nEvents\n-----------------------------------\n\nThe classes extends [EventEmitter](https://nodejs.org/api/events.html) which allows you to hook into different events.\n\nSee [event docs](docs/events.md) for detailed information + examples.\n\nBar Formatting\n-----------------------------------\n\nThe progressbar can be customized by using the following build-in placeholders. They can be combined in any order.\n\n- `{bar}` - the progress bar, customizable by the options **barsize**, **barCompleteString** and **barIncompleteString**\n- `{percentage}` - the current progress in percent (0-100)\n- `{total}` - the end value\n- `{value}` - the current value set by last `update()` call\n- `{eta}` - expected time of accomplishment in seconds (limmited to 115days, otherwise INF is displayed)\n- `{duration}` - elapsed time in seconds\n- `{eta_formatted}` - expected time of accomplishment formatted into appropriate units\n- `{duration_formatted}` - elapsed time formatted into appropriate units\n- `{\u003cpayloadKeyName\u003e}` - the payload value identified by its key\n\n### Example ###\n\n```js\nconst opt = {\n    format: 'progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}'\n}\n```\n\nis rendered as\n\n```\nprogress [========================================] 100% | ETA: 0s | 200/200\n```\n\nCustom formatters\n-----------------------------------\n\nInstead of a \"static\" format string it is also possible to pass a custom callback function as formatter.\nFor a full example (including params) take a look on `lib/formatter.js`\n\n### Example 1 ###\n\n```js\nfunction formatter(options, params, payload){\n\n    // bar grows dynamically by current progress - no whitespaces are added\n    const bar = options.barCompleteString.substr(0, Math.round(params.progress*options.barsize));\n\n    // end value reached ?\n    // change color to green when finished\n    if (params.value \u003e= params.total){\n        return '# ' + colors.grey(payload.task) + '   ' + colors.green(params.value + '/' + params.total) + ' --[' + bar + ']-- ';\n    }else{\n        return '# ' + payload.task + '   ' + colors.yellow(params.value + '/' + params.total) + ' --[' + bar + ']-- ';\n    }\n}\n\nconst opt = {\n    format: formatter\n}\n```\n\nis rendered as\n\n```\n# Task 1     0/200 --[]--\n# Task 1     98/200 --[████████████████████]--\n# Task 1     200/200 --[████████████████████████████████████████]--\n```\n\n\n### Example 2 ###\n\nYou can also access the default format functions to use them within your formatter:\n\n```js\nconst {TimeFormat, ValueFormat, BarFormat, Formatter} = require('cli-progess').Format;\n...\n```\n\nExamples\n---------------------------------------------\n\n### Example 1 - Set Options ###\n\n```js\n// change the progress characters\n// set fps limit to 5\n// change the output stream and barsize\nconst bar = new _progress.Bar({\n    barCompleteChar: '#',\n    barIncompleteChar: '.',\n    fps: 5,\n    stream: process.stdout,\n    barsize: 65,\n    position: 'center'\n});\n```\n\n### Example 2 - Change Styles defined by Preset ###\n\n```js\n// uee shades preset\n// change the barsize\nconst bar = new _progress.Bar({\n    barsize: 65,\n    position: 'right'\n}, _progress.Presets.shades_grey);\n```\n\n### Example 3 - Custom Payload ###\n\nThe payload object keys should only contain keys matching standard `\\w+` regex!\n\n```js\n// create new progress bar with custom token \"speed\"\nconst bar = new _progress.Bar({\n    format: 'progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total} | Speed: {speed} kbit'\n});\n\n// initialize the bar - set payload token \"speed\" with the default value \"N/A\"\nbar.start(200, 0, {\n    speed: \"N/A\"\n});\n\n// some code/update loop\n// ...\n\n// update bar value. set custom token \"speed\" to 125\nbar.update(5, {\n    speed: '125'\n});\n\n// process finished\nbar.stop();\n```\n\n### Example 4 - Custom Presets ###\n\n**File** `myPreset.js`\n\n```js\nconst colors = require('ansi-colors');\n\nmodule.exports = {\n    format: colors.red(' {bar}') + ' {percentage}% | ETA: {eta}s | {value}/{total} | Speed: {speed} kbit',\n    barCompleteChar: '\\u2588',\n    barIncompleteChar: '\\u2591'\n};\n```\n\n**Application**\n\n```js\nconst myPreset = require('./myPreset.js');\n\nconst bar = new _progress.Bar({\n    barsize: 65\n}, myPreset);\n```\n\n\nPresets/Themes\n---------------------------------------------\n\nNeed a more modern appearance ? **cli-progress** supports predefined themes via presets. You are welcome to add your custom one :)\n\nBut keep in mind that a lot of the \"special-chars\" rely on Unicode - it might not work as expected on legacy systems.\n\n### Default Presets ###\n\nThe following presets are included by default\n\n* **legacy** - Styles as of cli-progress v1.3.0\n* **shades-classic** - Unicode background shades are used for the bar\n* **shades-grey** - Unicode background shades with grey bar\n* **rect** - Unicode Rectangles\n\n\nCompatibility\n---------------------------------------------\n\n**cli-progress** is designed for linux/macOS/container applications which mostly providing standard compliant tty terminals/shells. In non-tty mode it is suitable to be used with logging daemons (cyclic output).\n\nIt also works with PowerShell on Windows 10 - the legacy command prompt on outdated Windows versions won't work as expected and is not supported!\n\nAny Questions ? Report a Bug ? Enhancements ?\n---------------------------------------------\nPlease open a new issue on [GitHub](https://github.com/npkgz/cli-progress/issues)\n\nLicense\n-------\nCLI-Progress is OpenSource and licensed under the Terms of [The MIT License (X11)](http://opensource.org/licenses/MIT). You're welcome to [contribute](https://github.com/npkgz/cli-progress/blob/master/CONTRIBUTE.md)!\n","funding_links":[],"categories":["Repository","JavaScript","Node.js / JavaScript 🟨","cli"],"sub_categories":["Command-line Utilities"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpkgz%2Fcli-progress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpkgz%2Fcli-progress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpkgz%2Fcli-progress/lists"}