{"id":12967,"library":"cli-progress-footer","title":"CLI Progress Footer","description":"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.","status":"active","version":"2.3.3","language":"javascript","source_language":"en","source_url":"https://github.com/medikoo/cli-progress-footer","tags":["javascript"],"install":[{"cmd":"npm install cli-progress-footer","lang":"bash","label":"npm"},{"cmd":"yarn add cli-progress-footer","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-progress-footer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for terminal color manipulation and formatting output, as noted in maintenance improvements for relying on its latest version.","package":"cli-color","optional":false}],"imports":[{"note":"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.","wrong":"import cliProgressFooter from 'cli-progress-footer';\n// Or\nconst cliProgressFooter = require('cli-progress-footer');","symbol":"cliProgressFooter","correct":"const cliProgressFooter = require('cli-progress-footer')();"},{"note":"`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.","wrong":"updateProgress('...');","symbol":"updateProgress","correct":"const cliProgressFooter = require('cli-progress-footer')();\ncliProgressFooter.updateProgress('...');"},{"note":"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.","wrong":"process.stdout.write('Regular log message\\n');","symbol":"writeStdout","correct":"const cliProgressFooter = require('cli-progress-footer')();\ncliProgressFooter.writeStdout('Regular log message\\n');"}],"quickstart":{"code":"const cliProgressFooter = require('cli-progress-footer')();\n\n// Configure throbber animation\ncliProgressFooter.shouldAddProgressAnimationPrefix = true;\ncliProgressFooter.progressAnimationPrefixFrames = ['\\u280B', '\\u2819', '\\u2839', '\\u2838', '\\u283C', '\\u2834', '\\u2826', '\\u2807'];\n\n// Simulate a task with dynamic progress\nlet progress = 0;\nconst totalSteps = 10;\nlet currentStep = 0;\n\nconst interval = setInterval(() => {\n  currentStep++;\n  progress = Math.min((currentStep / totalSteps) * 100, 100);\n  const message = `# Processing data: ${progress.toFixed(0)}% complete...`;\n  cliProgressFooter.updateProgress(message);\n\n  if (currentStep === Math.floor(totalSteps / 3)) {\n    cliProgressFooter.writeStdout('Intermediate log: Initial setup complete.\\n');\n  }\n\n  if (currentStep === Math.floor(totalSteps / 3 * 2)) {\n    cliProgressFooter.writeStdout('Intermediate log: Processing part two.\\n');\n  }\n\n  if (currentStep >= totalSteps) {\n    clearInterval(interval);\n    // Clear the progress footer and write a final message\n    cliProgressFooter.updateProgress(''); // Clear progress message\n    cliProgressFooter.writeStdout('Task completed successfully! All data processed.\\n');\n    process.exit(0);\n  }\n}, 300);\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Ensure `overrideStdout: true` (default) and use `cliProgressFooter.writeStdout(data)` for all regular output instead of `process.stdout.write(data)`.","message":"Direct 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure `redirectStderr: true` (default) or, if opting out, ensure no critical output goes to `process.stderr` that could conflict with the footer.","message":"Direct 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Keep `workaroundChildProcess: true` (default). This setting decorates `child_process` functions to temporarily hide the progress bar during problematic child process execution.","message":"Child 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to `cli-progress-footer` version `2.3.3` or newer to resolve issues with `\\r` characters in progress messages.","message":"Versions 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.","severity":"breaking","affected_versions":"<2.3.3"},{"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.","message":"If `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.","severity":"gotcha","affected_versions":">=2.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const cliProgressFooter = require('cli-progress-footer');` to `const cliProgressFooter = require('cli-progress-footer')();`","cause":"The `require('cli-progress-footer')` call did not include the `()` to invoke the factory function, returning the function itself instead of the initialized instance.","error":"TypeError: cliProgressFooter is not a function"},{"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()`.","cause":"External writes to `process.stdout` or `process.stderr` that bypass the `cli-progress-footer` utility are interfering with its controlled output stream.","error":"Progress bar or output gets corrupted/jumbled intermittently."},{"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.","cause":"A child process spawned with `stdio: 'inherit'` is writing directly to the console, which `cli-progress-footer` cannot intercept or manage.","error":"Progress display temporarily disappears or breaks when I run a child process."},{"fix":"Upgrade `cli-progress-footer` to version `2.3.3` or newer, which contains a fix for `\\r` character handling.","cause":"Using `\\r` (carriage return) characters in progress messages with older versions of the library, which had a bug in handling them.","error":"Progress message has strange characters or misaligned lines when using carriage returns (`\\r`)."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}