cli-progress

What is cli-progress?

The cli-progress package is a versatile library for Node.js designed to create customizable progress bars in the command line interface (CLI). It supports various styles, custom tokens, and can handle multiple bars simultaneously, making it suitable for applications that require real-time progress feedback.

What are cli-progress's main functionalities?

Single Progress Bar

This demonstrates how to create a simple progress bar that updates from 0 to 50 out of 100. It uses the 'shades_classic' preset for styling.

const cliProgress = require('cli-progress');
const bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);
bar.start(100, 0);
bar.update(50);
bar.stop();

Multiple Progress Bars

This example shows how to manage multiple progress bars simultaneously. It creates two bars with different total values and updates them independently.

const cliProgress = require('cli-progress');
const multiBar = new cliProgress.MultiBar({ clearOnComplete: false, hideCursor: true }, cliProgress.Presets.shades_grey);
const bar1 = multiBar.create(200, 0);
const bar2 = multiBar.create(100, 0);
bar1.increment();
bar2.update(20);
multiBar.stop();

Custom Tokens

This code snippet illustrates how to use custom tokens within the progress bar format. It displays additional information like speed alongside the progress.

const cliProgress = require('cli-progress');
const customBar = new cliProgress.SingleBar({ format: 'Progress |{bar}| {percentage}% || {value}/{total} Chunks || Speed: {speed}' }, cliProgress.Presets.shades_classic);
customBar.start(100, 0, { speed: 'N/A' });
customBar.update(40, { speed: '4MB/s' });
customBar.stop();

Other packages similar to cli-progress

progress

The 'progress' package offers a simpler, more streamlined approach to progress bars in Node.js. While it lacks some of the advanced features and customization options of cli-progress, it's a solid choice for basic needs.

nanobar

Nanobar is primarily focused on creating lightweight progress bars for web applications. Unlike cli-progress, which is designed for CLI applications, Nanobar is for frontend development, showcasing the versatility in application contexts.

progressbar.js

progressbar.js provides a more visually rich set of progress bars for web applications, including circular progress bars and other shapes. It's more suited for graphical interfaces compared to cli-progress, which is tailored for CLI environments.

README

CLI-Progress

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

$ npm install cli-progress

Presets

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
• Preset/Theme support

Successful tested on Windows10, Debian 8 and Ubuntu 14,15,16

Installation

You can install cli-progress with NPM

$ npm install cli-progress
$ yarn add cli-progress

Or manually from the GitHub Repository

$ wget https://github.com/AndiDittrich/Node.CLI-Progress/archive/v1.4.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 and use shades_classic theme
var bar1 = new _progress.Bar({}, _progress.Presets.shades_classic);

// 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, preset: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
});

Presets/Themes

Need a more modern appearance ? cli-progress supports predefined themes via presets. You are welcome to add your custom one :)

But keep in mind that a lot of the "special-chars" rely on Unicode - it might not work as expected on legacy systems.

Default Presets

The following presets are included by default

• legacy - Styles as of cli-progress v1.3.0
• shades-classic - Unicode background shades are used for the bar
• shades-grey - Unicode background shades with grey bar
• rect - Unicode Rectangles

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!