⌛️ Easy to use Progress-Bar for Command-Line/Terminal Applications written in Node.js
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
CHANGES.md added stopOnComplete example; version 1.3.0 Dec 2, 2016
CONTRIBUTE.md initial Dec 13, 2015
LICENSE.md prepared release v1.2.0 Jul 19, 2016
README.md Add option to automatcially `stop` on completion Nov 29, 2016
main.js initial Dec 13, 2015
package.json added stopOnComplete example; version 1.3.0 Dec 2, 2016
video.gif added .gif video example Dec 13, 2015



Easy to use Progress-Bar for Command-Line/Terminal Applications

$ npm install cli-progress



  • Simple, Robust and Easy to use
  • Full customizable output format (various placeholders are available)
  • Custom Bar Characters
  • FPS limiter
  • ETA calculation based on elapsed time
  • Only visible in TTY environments
  • No callbacks required - designed as pure, external controlled UI widget
  • Works in Asynchronous and Synchronous tasks

Successful tested on Windows10, Debian 8.2 and Ubuntu 14 LTS


You can install cli-progress with NPM

$ npm install cli-progress

Or manually from the GitHub Repository

$ wget https://github.com/AndiDittrich/Node.CLI-Progress/archive/v1.1.0.tar.gz


Getting Started

You can find some basic examples in example.js - just run the file with $ node example.js


var _progress = require('cli-progress');

// create a new progress bar instance
var bar1 = new _progress.Bar();

// start the progress bar with a total value of 200 and start value of 0
bar1.start(200, 0);

// update the current value in your application..

// stop the progress bar



Initialize a new Progress bar. An instance can be used multiple times! it's not required to re-create it!

var <instance> = new namespace.Bar(options:object);


Starts the progress bar and set the total and initial value

<instance>.start(totalValue:int, startValue:int);


Sets the current progress value



Increases the current progress value by a specified amount (default +1)



Stops the progress bar and go to next line


Bar Formatting

The progressbar can be customized by using the following build-in placeholders. They can be combined in any order.

  • {bar} - the progress bar, customizable by the options barsize, barCompleteString and barIncompleteString
  • {percentage} - the current progress in percent (0-100)
  • {total} - the end value
  • {value} - the current value set by last update() call
  • {eta} - expected time of accomplishment in seconds
  • {duration} - elapsed time in seconds
  • {eta_formatted} - expected time of accomplishment formatted into appropriate units
  • {duration_formatted} - elapsed time formatted into appropriate units


progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}

is rendered as

progress [========================================] 100% | ETA: 0s | 200/200


  • format (type:string) - progress bar output format @see format section
  • fps (type:float) - the maximum update rate (default: 10)
  • stream (type:stream) - output stream to use (default: process.stderr)
  • stopOnComplete (type:boolean) - automatically call stop() when the value reaches the total (default: false)
  • clearOnComplete (type:boolean) - clear the progress bar on complete / stop() call (default: false)
  • barsize (type:int) - the length of the progress bar in chars (default: 40)
  • barCompleteString (type:char) - character to use as "complete" indicator in the bar (default: "=")
  • barIncompleteString (type:char) - character to use as "incomplete" indicator in the bar (default: "-")
  • hideCursor (type:boolean) - hide the cursor during progress operation; restored on complete (default: false)
  • etaBuffer (type:int) - number of updates with which to calculate the eta; higher numbers give a more stable eta (default: 10)


// change the progress characters
// set fps limit to 5
// change the output stream and barsize
var b2 = new _progress.Bar({
    barCompleteChar: '#',
    barIncompleteChar: '.',
    fps: 5,
    stream: process.stdout,
    barsize: 65

Any Questions ? Report a Bug ? Enhancements ?

Please open a new issue on GitHub


CLI-Progress is OpenSource and licensed under the Terms of The MIT License (X11). You're welcome to contribute!