⌛️ Easy to use Progress-Bar for Command-Line/Terminal Applications written in Node.js
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
.gitignore
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
example-synchronous.js
example.js
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

README.md

CLI-Progress

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

$ npm install cli-progress

Demo

Features

  • 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

Installation

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

Progress-Bar

Getting Started

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

Usage

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..
bar1.update(100);

// stop the progress bar
bar1.stop();

Methods/Syntax

Constructor

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);

start()

Starts the progress bar and set the total and initial value

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

update()

Sets the current progress value

<instance>.update(currentValue:int);

increment()

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

<instance>.increment(delta:int);

stop()

Stops the progress bar and go to next line

<instance>.stop();

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

Example

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

is rendered as

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

Options

  • 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)

Example

// 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

License

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