Repository files navigation

Single Bar |Multi Bar |Options |Examples |Presets |Events

easy to use progress-bar for command-line/terminal applications

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

• Simple,Robust andEasy to use
• Full customizable output format (various placeholders are available)
• Single progressbar mode
• Multi progessbar mode
• Custom Bar Characters
• FPS limiter
• ETA calculation based on elapsed time
• Custom Tokens to display additional data (payload) within the bar
• TTY and NOTTY mode
• No callbacks required - designed as pure, external controlled UI widget
• Works in Asynchronous and Synchronous tasks
• Preset/Theme support
• Custom bar formatters (via callback)
• Logging during multibar operation

Multiple examples are available e.g.example.js - just try it$ node example.js

constcliProgress=require('cli-progress');// create a new progress bar instance and use shades_classic themeconstbar1=newcliProgress.SingleBar({},cliProgress.Presets.shades_classic);// start the progress bar with a total value of 200 and start value of 0bar1.start(200,0);// update the current value in your application..bar1.update(100);// stop the progress barbar1.stop();

constcliProgress=require('cli-progress');// note: you have to install this dependency manually since it's not required by cli-progressconstcolors=require('ansi-colors');// create new progress barconstb1=newcliProgress.SingleBar({format:'CLI Progress |'+colors.cyan('{bar}')+'| {percentage}% || {value}/{total} Chunks || Speed: {speed}',barCompleteChar:'\u2588',barIncompleteChar:'\u2591',hideCursor:true});// initialize the bar - defining payload token "speed" with the default value "N/A"b1.start(200,0,{speed:"N/A"});// update valuesb1.increment();b1.update(20);// stop the barb1.stop();

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

constcliProgress=require('cli-progress');const<instance> = new cliProgress.SingleBar(options:object [, preset:object]);

Starts the progress bar and set the total and initial value

<instance>.start(totalValue:int, startValue:int [, payload:object ={}]);

Sets the current progress value and optionally the payload with values of custom tokens as a second parameter. To update payload only, set currentValue tonull.

<instance>.update([currentValue:int [, payload:object ={}]]);// update progress without altering value<instance>.update([payload:object ={}]);

Increases the current progress value by a specified amount (default +1). Update payload optionally

<instance>.increment([delta:int [, payload:object ={}]]);// delta=1 assumed<instance>.increment(payload:object ={}]);

Sets the total progress value while progressbar is active. Especially useful handling dynamic tasks.

<instance>.setTotal(totalValue:int);

Stops the progress bar and go to next line

<instance>.stop();

Force eta calculation update (long running processes) without altering the progress values.

Note: you may want to increaseetaBuffer size - otherwise it can causeINF eta values in case the value didn't changed within the time series.

<instance>.updateETA();

constcliProgress=require('cli-progress');// create new containerconstmultibar=newcliProgress.MultiBar({clearOnComplete:false,hideCursor:true,format:' {bar} | {filename} | {value}/{total}',},cliProgress.Presets.shades_grey);// add barsconstb1=multibar.create(200,0);constb2=multibar.create(1000,0);// control barsb1.increment();b2.update(20,{filename:"test1.txt"});b1.update(20,{filename:"helloworld.txt"});// stop all barsmultibar.stop();

Initialize a new multiprogress container. Bars need to be added. The options/presets are used for each single bar!

constcliProgress=require('cli-progress');const<instance> = new cliProgress.MultiBar(options:object [, preset:object]);

Adds a new progress bar to the container and starts the bar. Returns regularSingleBar object which can be individually controlled.

AdditionalbarOptions can be passed directly to thegeneric-bar 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..

const<barInstance> =<instance>.create(totalValue:int, startValue:int [, payload:object ={} [, barOptions:object ={}]]);

Removes an existing bar from the multi progress container.

<instance>.remove(<barInstance>:object);

Stops the all progress bars

<instance>.stop();

Outputs (buffered) content on top of the multibars during operation.

Notice: newline at the end is required

Example:example-logging.js

<instance>.log("Hello World\n");

The following options can be changed

• format (type:string|function) - 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 callstop() 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)
• align (type:char) - position of the progress bar - 'left' (default), 'right' or 'center'
• barCompleteChar (type:char) - character to use as "complete" indicator in the bar (default: "=")
• barIncompleteChar (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) - passnull to keep terminal settings
• linewrap (type:boolean) - disable line wrapping (default: false) - passnull to keep terminal settings; passtrue to add linebreaks automatically (not recommended)
• gracefulExit (type:boolean) - stop the bars in case ofSIGINT orSIGTERM - this restores most cursor settings before exiting (default:false - subjected to change)
• etaBuffer (type:int) - number of updates with which to calculate the eta; higher numbers give a more stable eta (default: 10)
• 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 loffps values and largeetaBuffer (default: false)
• progressCalculationRelative (type:boolean) - progress calculation usesstartValue as zero-offset (default: false)
• synchronousUpdate (type:boolean) - trigger redraw duringupdate() in case threshold time x2 is exceeded (default: true) - limited to single bar usage
• noTTYOutput (type:boolean) - enable scheduled output to notty streams - e.g. redirect to files (default: false)
• notTTYSchedule (type:int) - set the output schedule/interval for notty output inms (default: 2000ms)
• emptyOnZero (type:boolean) - display progress bars with 'total' of zero(0) as empty, not full (default: false)
• 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)
• 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!
• autopadding (type: boolean) - add padding chars to formatted time and percentage to force fixed width (default: false) - Note: handled standard format functions!
• autopaddingChar (type: string) - the character sequence used for autopadding (default: " ") - Note: due to performance optimizations this value requires a length of 3 identical chars
• formatBar (type: function) - a custom bar formatter function which renders the bar-element (default:format-bar.js)
• formatTime (type: function) - a custom timer formatter function which renders the formatted time elements likeeta_formatted andduration-formatted (default:format-time.js)
• formatValue (type: function) - a custom value formatter function which renders all other values (default:format-value.js)

The classes extendsEventEmitter which allows you to hook into different events.

Seeevent docs for detailed information + examples.

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 optionsbarsize,barCompleteString andbarIncompleteString
• {percentage} - the current progress in percent (0-100)
• {total} - the end value
• {value} - the current value set by lastupdate() call
• {eta} - expected time of accomplishment in seconds (limmited to 115days, otherwise INF is displayed)
• {duration} - elapsed time in seconds
• {eta_formatted} - expected time of accomplishment formatted into appropriate units
• {duration_formatted} - elapsed time formatted into appropriate units
• {<payloadKeyName>} - the payload value identified by its key

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

is rendered as

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

Instead of a "static" format string it is also possible to pass a custom callback function as formatter.For a full example (including params) take a look onlib/formatter.js

functionformatter(options,params,payload){// bar grows dynamically by current progress - no whitespaces are addedconstbar=options.barCompleteString.substr(0,Math.round(params.progress*options.barsize));// end value reached ?// change color to green when finishedif(params.value>=params.total){return'# '+colors.grey(payload.task)+'   '+colors.green(params.value+'/'+params.total)+' --['+bar+']-- ';}else{return'# '+payload.task+'   '+colors.yellow(params.value+'/'+params.total)+' --['+bar+']-- ';}}constopt={format:formatter}

is rendered as

# Task 1     0/200 --[]--# Task 1     98/200 --[████████████████████]--# Task 1     200/200 --[████████████████████████████████████████]--

You can also access the default format functions to use them within your formatter:

const{TimeFormat, ValueFormat, BarFormat, Formatter}=require('cli-progess').Format;...

// change the progress characters// set fps limit to 5// change the output stream and barsizeconstbar=new_progress.Bar({barCompleteChar:'#',barIncompleteChar:'.',fps:5,stream:process.stdout,barsize:65,position:'center'});

// uee shades preset// change the barsizeconstbar=new_progress.Bar({barsize:65,position:'right'},_progress.Presets.shades_grey);

The payload object keys should only contain keys matching standard\w+ regex!

// create new progress bar with custom token "speed"constbar=new_progress.Bar({format:'progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total} | Speed: {speed} kbit'});// initialize the bar - set payload token "speed" with the default value "N/A"bar.start(200,0,{speed:"N/A"});// some code/update loop// ...// update bar value. set custom token "speed" to 125bar.update(5,{speed:'125'});// process finishedbar.stop();

FilemyPreset.js

constcolors=require('ansi-colors');module.exports={format:colors.red(' {bar}')+' {percentage}% | ETA: {eta}s | {value}/{total} | Speed: {speed} kbit',barCompleteChar:'\u2588',barIncompleteChar:'\u2591'};

Application

constmyPreset=require('./myPreset.js');constbar=new_progress.Bar({barsize:65},myPreset);

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.

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

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

It also works with PowerShell on Windows 10 - the legacy command prompt on outdated Windows versions won't work as expected and is not supported!

Please open a new issue onGitHub

CLI-Progress is OpenSource and licensed under the Terms ofThe MIT License (X11). You're welcome tocontribute!