Registry / devops / cli-progress

cli-progress

JSON →
library2.0.0jsnpmunverified

cli-progress is a robust and highly customizable library for displaying interactive progress bars in Node.js command-line and terminal applications. Currently stable at version 3.12.0, it sees active development with several releases per year, ensuring continuous improvement and bug fixes. Key features include full control over output formatting, support for both single and multiple concurrent progress bars, and the ability to define custom tokens for displaying additional data (payloads). It offers various presets for quick styling and operates without requiring callbacks, being designed as an externally controlled UI widget suitable for both asynchronous and synchronous tasks. Unlike many alternatives, its focus on external control provides flexibility, and it includes features like FPS limiting and TTY/NOTTY mode handling.

devopsobservability
npm install cli-progress
github ↗package ↗
INSTALL
IMPORT
SIG · CLI-PROGRESS
C
cli-progress
devopsjavascriptv2.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

cliProgress
✓ import cliProgress from 'cli-progress';
✗ import { cliProgress } from 'cli-progress';
As 'cli-progress' is a CommonJS module, ESM users should use the default import pattern (e.g., `import cliProgress from 'cli-progress';`) which leverages Node.js's CJS interop. Named imports for the main module object are not supported directly.
SingleBar
✓ const cliProgress = require('cli-progress'); const bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);
✗ import { SingleBar } from 'cli-progress';
`SingleBar` is a class property of the main `cliProgress` object. In ESM, it's accessed via `cliProgress.SingleBar` after a default import. Direct named imports are incorrect for this CommonJS package.
MultiBar
✓ const cliProgress = require('cli-progress'); const multiBar = new cliProgress.MultiBar({}, cliProgress.Presets.shades_classic);
✗ import { MultiBar } from 'cli-progress';
`MultiBar` is a class property of the main `cliProgress` object. In ESM, it's accessed via `cliProgress.MultiBar` after a default import. Direct named imports are incorrect for this CommonJS package.
Presets
✓ import cliProgress from 'cli-progress'; const theme = cliProgress.Presets.shades_classic;
✗ const { Presets } = require('cli-progress');
`Presets` is an object property of the main `cliProgress` export. Access it via `cliProgress.Presets` in both CommonJS and ESM environments.

Demonstrates a single progress bar with custom formatting, colors (using 'ansi-colors'), and a dynamic payload token update.

const cliProgress = require('cli-progress'); const colors = require('ansi-colors'); // Install 'ansi-colors' manually: npm install ansi-colors // Create new progress bar instance const b1 = new cliProgress.SingleBar({ format: 'CLI Progress |' + colors.cyan('{bar}') + '| {percentage}% || {value}/{total} Chunks || Speed: {speed}', barCompleteChar: '\u2588', barIncompleteChar: '\u2591', hideCursor: true }); // Initialize the bar with total 200, start value 0, and a custom payload token 'speed' b1.start(200, 0, { speed: "N/A" }); let value = 0; const timer = setInterval(() => { value += 5; b1.update(value, { speed: `${(Math.random() * 10).toFixed(2)} MB/s` }); if (value >= b1.getTotal()) { clearInterval(timer); b1.stop(); console.log('Progress complete!'); } }, 100);
Debug
Known issues
breakingSynchronous updates on MultiBar instances could cause unexpected behavior prior to v3.3.1. The fix in v3.3.1 effectively limited synchronous updates to SingleBar instances to prevent these issues.
fix
Upgrade to v3.3.1 or higher. If you require synchronous multi-bar updates, thoroughly test your implementation on newer versions or consider alternative approaches for synchronization.
affects: <3.3.1
gotchaColorized progress bars (e.g., using `colors.cyan('{bar}')`) will throw a `ReferenceError` if the `ansi-colors` package is not manually installed, as it is an optional peer dependency for styling.
fix
Ensure `ansi-colors` is installed in your project: `npm install ansi-colors` or `yarn add ansi-colors`.
affects: >=1.4.1
gotchaThe maximum displayed ETA value has been adjusted in different versions (e.g., limited to 100000s in v2.1.0, then to 1e7 seconds in v3.9.0). If the calculated ETA exceeds this limit, it will display as 'INF'.
fix
Review any code that relies on specific large ETA display values. If precise display beyond the current limit is critical, consider implementing a custom ETA formatter.
affects: >=2.1.0
gotchaFor very long-running processes or processes with infrequent updates, the ETA calculation may incorrectly display 'INF' if the `etaBuffer` option is not sufficiently large to capture enough historical data points.
fix
Increase the `etaBuffer` option in the `SingleBar` or `MultiBar` constructor options to a value appropriate for your process's duration and update frequency.
affects: >=2.1.0
Errors
Common errors & fixes
ReferenceError: colors is not defined
The `ansi-colors` package, which is used for colorizing the progress bar, has not been installed.
fix
Install the `ansi-colors` package: `npm install ansi-colors` or `yarn add ansi-colors`.
TypeError: cliProgress.SingleBar is not a constructor
Attempting to use ES module named imports for `SingleBar` (e.g., `import { SingleBar } from 'cli-progress';`) when 'cli-progress' is a CommonJS module.
fix
For ESM, use a default import for the main module object: `import cliProgress from 'cli-progress';` and then access `SingleBar` as a property: `new cliProgress.SingleBar(...)`. For CommonJS, use `const cliProgress = require('cli-progress');`.
ETA displays as 'INF' or 'NULL'
This can happen if the progress bar is initialized with zero total and current values (0/0), if the ETA calculation buffer (`etaBuffer`) is too small for long processes, or if progress updates are too infrequent.
fix
Ensure `start()` is called with a meaningful total, increase the `etaBuffer` option in the constructor for long-running tasks, and ensure regular updates to the progress value.
Upgrade
Version history
2.0.0latest on npm
Audit
Dependencies
ansi-colorsoptionalOptional dependency for adding color to progress bars. Must be installed manually if colorization is desired.
Agent activity
38 hits · last 30 days
node
32
OpenAI (training)
1
Resources
githubhttps://github.com/npkgz/cli-progress ↗
packagehttps://www.npmjs.com/package/cli-progress ↗
cli-progress — npm install cli-progress · libregistry