or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdmulti-bar.mdpresets-formatting.mdsingle-bar.md
tile.json

index.mddocs/

CLI Progress

CLI Progress is a comprehensive terminal progress bar library that enables developers to create visual progress indicators for command-line and terminal applications. It supports both single and multi-progress bar modes with extensive customization options including custom bar characters, formatting, themes/presets, and real-time progress tracking.

Package Information

  • Package Name: cli-progress
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install cli-progress

Core Imports

const cliProgress = require('cli-progress');

For ES modules:

import * as cliProgress from 'cli-progress';

Basic Usage

const cliProgress = require('cli-progress');

// Create a single progress bar with preset
const bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);

// Start the progress bar with total value of 100
bar.start(100, 0);

// Update progress
bar.update(50);

// Stop the progress bar
bar.stop();

Architecture

CLI Progress is built around several key components:

  • SingleBar: Individual progress bar with automatic rendering and terminal management
  • MultiBar: Container for coordinating multiple progress bars with event-driven updates
  • Presets: Built-in themes and styling configurations for common visual patterns
  • Formatters: Customizable rendering system with token-based templating and format utilities
  • Terminal Management: Low-level cursor control, TTY detection, and graceful cleanup

Capabilities

Single Progress Bar

Individual progress bar implementation with automatic rendering, ETA calculation, and comprehensive customization options.

class SingleBar extends GenericBar {
  constructor(options?: ProgressBarOptions, preset?: PresetConfiguration);
  start(total: number, startValue?: number, payload?: object): void;
  update(current?: number, payload?: object): void;
  increment(delta?: number, payload?: object): void;
  stop(): void;
  setTotal(total: number): void;
  updateETA(): void;
}

// Bar is an alias for SingleBar for convenience
const Bar = SingleBar;

Single Progress Bar

Multi Progress Bar

Container for managing multiple progress bars simultaneously with coordinated rendering and logging capabilities.

class MultiBar extends EventEmitter {
  constructor(options?: ProgressBarOptions, preset?: PresetConfiguration);
  create(total: number, startValue?: number, payload?: object, barOptions?: object): SingleBar;
  remove(bar: SingleBar): boolean;
  stop(): void;
  log(message: string): void;
}

Multi Progress Bar

Presets and Formatting

Built-in themes and advanced formatting system for creating custom progress bar appearances.

interface Presets {
  legacy: PresetConfiguration;
  shades_classic: PresetConfiguration;
  shades_grey: PresetConfiguration;
  rect: PresetConfiguration;
}

interface Format {
  Formatter: (options: ProgressBarOptions, params: FormatParams, payload: object) => string;
  BarFormat: (progress: number, options: ProgressBarOptions) => string;
  ValueFormat: (value: any, options: ProgressBarOptions, type: string) => any;
  TimeFormat: (seconds: number, options: ProgressBarOptions, roundTo?: number) => string;
}

Presets and Formatting

Types

interface ProgressBarOptions {
  // Visual options
  format?: string | function;
  barsize?: number;
  align?: 'left' | 'right' | 'center';
  barCompleteChar?: string;
  barIncompleteChar?: string;
  barGlue?: string;
  hideCursor?: boolean;
  linewrap?: boolean;
  
  // Behavior options
  fps?: number;
  stream?: NodeJS.WriteStream;
  stopOnComplete?: boolean;
  clearOnComplete?: boolean;
  gracefulExit?: boolean;
  synchronousUpdate?: boolean;
  noTTYOutput?: boolean;
  notTTYSchedule?: number;
  emptyOnZero?: boolean;
  forceRedraw?: boolean;
  
  // ETA and calculation options
  etaBuffer?: number;
  etaAsynchronousUpdate?: boolean;
  progressCalculationRelative?: boolean;
  
  // Formatting options
  autopadding?: boolean;
  autopaddingChar?: string;
  formatBar?: (progress: number, options: ProgressBarOptions) => string;
  formatTime?: (seconds: number, options: ProgressBarOptions, roundTo?: number) => string;
  formatValue?: (value: any, options: ProgressBarOptions, type: string) => any;
  terminal?: object;
}

interface PresetConfiguration {
  format?: string;
  barCompleteChar?: string;
  barIncompleteChar?: string;
  [key: string]: any;
}

interface FormatParams {
  progress: number;
  eta: number;
  startTime: number;
  stopTime?: number;
  total: number;
  value: number;
  maxWidth: number;
}