Registry / devops / cli-progress-footer

cli-progress-footer

JSON →
library2.3.3jsnpmunverified

cli-progress-footer is a Node.js utility for managing dynamic progress content displayed consistently below the standard output stream in command-line interfaces. The package, currently stable at version 2.3.3, receives maintenance updates and bug fixes (e.g., a fix for `\r` characters in v2.3.3) rather than a fixed release cadence. Its key differentiator is its robust handling of `process.stdout.write` and `process.stderr` by default, ensuring that dynamic progress information remains at the bottom of the terminal, even when other parts of the application or child processes are writing to the console. It also includes a workaround for child processes that might otherwise disrupt the progress display, making it reliable for complex CLI tools. The library is content-agnostic, allowing any string to be used for the progress message.

devops
npm install cli-progress-footer
github ↗package ↗
INSTALL
IMPORT
SIG · CLI-PROGRESS-FOOTE
C
cli-progress-footer
devopsjavascriptv2.3.3
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.

cliProgressFooter
✓ const cliProgressFooter = require('cli-progress-footer')();
✗ import cliProgressFooter from 'cli-progress-footer'; // Or const cliProgressFooter = require('cli-progress-footer');
The package exports a factory function as its default export. It must be called immediately after requiring it to get the progress footer instance, which is the main interaction point for controlling the footer.
updateProgress
✓ const cliProgressFooter = require('cli-progress-footer')(); cliProgressFooter.updateProgress('...');
✗ updateProgress('...');
`updateProgress` is a method of the `cliProgressFooter` instance, not a direct export. It is used to set or update the content displayed in the progress footer.
writeStdout
✓ const cliProgressFooter = require('cli-progress-footer')(); cliProgressFooter.writeStdout('Regular log message\n');
✗ process.stdout.write('Regular log message\n');
When `overrideStdout` is `true` (default), direct writes to `process.stdout` can corrupt the progress display. Use `cliProgressFooter.writeStdout` for all regular application output to ensure it appears above the progress content.

Initializes a CLI progress footer, displays a dynamic progress message with a custom throbber animation, and demonstrates updating it below standard output while also writing regular log messages and ensuring proper cleanup upon task completion.

const cliProgressFooter = require('cli-progress-footer')(); // Configure throbber animation cliProgressFooter.shouldAddProgressAnimationPrefix = true; cliProgressFooter.progressAnimationPrefixFrames = ['\u280B', '\u2819', '\u2839', '\u2838', '\u283C', '\u2834', '\u2826', '\u2807']; // Simulate a task with dynamic progress let progress = 0; const totalSteps = 10; let currentStep = 0; const interval = setInterval(() => { currentStep++; progress = Math.min((currentStep / totalSteps) * 100, 100); const message = `# Processing data: ${progress.toFixed(0)}% complete...`; cliProgressFooter.updateProgress(message); if (currentStep === Math.floor(totalSteps / 3)) { cliProgressFooter.writeStdout('Intermediate log: Initial setup complete.\n'); } if (currentStep === Math.floor(totalSteps / 3 * 2)) { cliProgressFooter.writeStdout('Intermediate log: Processing part two.\n'); } if (currentStep >= totalSteps) { clearInterval(interval); // Clear the progress footer and write a final message cliProgressFooter.updateProgress(''); // Clear progress message cliProgressFooter.writeStdout('Task completed successfully! All data processed.\n'); process.exit(0); } }, 300);
Debug
Known issues
gotchaDirect writes to `process.stdout` will bypass the progress footer and can corrupt the display if `overrideStdout` is `false`. By default, `overrideStdout` is `true`, meaning all application output *must* go through `cliProgressFooter.writeStdout` to maintain proper display order.
fix
Ensure `overrideStdout: true` (default) and use `cliProgressFooter.writeStdout(data)` for all regular output instead of `process.stdout.write(data)`.
affects: >=2.0.0
gotchaDirect writes to `process.stderr` can disrupt the progress footer display if `redirectStderr` is `false`. By default, `redirectStderr` is `true`, redirecting `stderr` to `stdout` to maintain consistent output order.
fix
Ensure `redirectStderr: true` (default) or, if opting out, ensure no critical output goes to `process.stderr` that could conflict with the footer.
affects: >=2.0.0
gotchaChild processes spawned with inherited `stdio` can break the progress display because their output cannot be controlled by `cli-progress-footer`. This can lead to corrupted or interleaved output.
fix
Keep `workaroundChildProcess: true` (default). This setting decorates `child_process` functions to temporarily hide the progress bar during problematic child process execution.
affects: >=2.0.0
breakingVersions prior to `v2.3.3` may experience issues where carriage return (`\r`) characters in progress output can break the display, leading to corrupted or misaligned progress lines.
fix
Upgrade to `cli-progress-footer` version `2.3.3` or newer to resolve issues with `\r` characters in progress messages.
affects: <2.3.3
gotchaIf `discardStdin` is set to `false`, user input via stdin will be echoed to the console, potentially appearing within or alongside the progress message. The cursor will also remain visible.
fix
For most use cases, keep `discardStdin: true` (default) to mute stdin input and hide the cursor, preventing user input from interfering with the progress display.
affects: >=2.2.0
Errors
Common errors & fixes
TypeError: cliProgressFooter is not a function
The `require('cli-progress-footer')` call did not include the `()` to invoke the factory function, returning the function itself instead of the initialized instance.
fix
Change `const cliProgressFooter = require('cli-progress-footer');` to `const cliProgressFooter = require('cli-progress-footer')();`
Progress bar or output gets corrupted/jumbled intermittently.
External writes to `process.stdout` or `process.stderr` that bypass the `cli-progress-footer` utility are interfering with its controlled output stream.
fix
Ensure `overrideStdout` and `redirectStderr` options are set to `true` (their defaults), and for any custom output, use `cliProgressFooter.writeStdout()` instead of direct `process.stdout.write()`.
Progress display temporarily disappears or breaks when I run a child process.
A child process spawned with `stdio: 'inherit'` is writing directly to the console, which `cli-progress-footer` cannot intercept or manage.
fix
Ensure the `workaroundChildProcess` option is set to `true` (its default). This enables internal logic to temporarily hide the progress bar during such child process executions.
Progress message has strange characters or misaligned lines when using carriage returns (`\r`).
Using `\r` (carriage return) characters in progress messages with older versions of the library, which had a bug in handling them.
fix
Upgrade `cli-progress-footer` to version `2.3.3` or newer, which contains a fix for `\r` character handling.
Upgrade
Version history
2.3.3latest on npm
Audit
Dependencies
cli-colorrequiredUsed internally for terminal color manipulation and formatting output, as noted in maintenance improvements for relying on its latest version.
Agent activity
7 hits · last 30 days
node
6
Resources
githubhttps://github.com/medikoo/cli-progress-footer ↗
packagehttps://www.npmjs.com/package/cli-progress-footer ↗
cli-progress-footer — npm install cli-progress-footer · libregistry