# cli-simple-progress

> Simple to use progress-bar for command-line/terminal applications

Latest version **2.0.0** (published 2020-11-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install cli-simple-progress
pnpm add cli-simple-progress
yarn add cli-simple-progress
bun add cli-simple-progress
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2020-11-28 |
| First published | 2019-12-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6 |
| Dependencies | 2 |
| Unpacked size | 10.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Jesse Feng |
| Maintainers | fengxinming |
| Keywords | cli, progress, progress-bar, log-update |

## Links

- npm: https://www.npmjs.com/package/cli-simple-progress
- Repository: https://github.com/fengxinming/cli-simple-progress
- Homepage: https://github.com/fengxinming/cli-simple-progress#readme
- Issues: https://github.com/fengxinming/cli-simple-progress/issues
- npm.io page: https://npm.io/package/cli-simple-progress

## Dependencies (2)

- [chalk](https://npm.io/package/chalk.md) ^4.1.0
- [log-update](https://npm.io/package/log-update.md) ^4.0.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2020-11-28
- 1.0.0 — 2019-12-30

## README

# cli-simple-progress

[![npm package](https://nodei.co/npm/cli-simple-progress.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/cli-simple-progress)

> Simple to use progress-bar for command-line/terminal applications

[![NPM version](https://img.shields.io/npm/v/cli-simple-progress.svg?style=flat)](https://npmjs.org/package/cli-simple-progress)
[![NPM Downloads](https://img.shields.io/npm/dm/cli-simple-progress.svg?style=flat)](https://npmjs.org/package/cli-simple-progress)

## Installation

```bash
$ npm install cli-simple-progress
```

## Usage

increase(value[, tokens])

```js
const bar = new ProgressBar({
  width: 30,
  template: `CLI Progress | ${chalk.green('{complete}')}${chalk.white('{incomplete}')} | {percent}% | {current}/{total}`,
  complete: '\u2588',
  incomplete: '\u2591'
});

const timer = setInterval(() => {
  bar.increase(Math.round(Math.random() * 10));
}, 50);
bar.on('complete', () => {
  clearInterval(timer);
});
```

progress(decimal[, tokens])

```js
const bar = new ProgressBar({
  width: 30,
  template: 'CLI Progress | {complete}{incomplete} | {percent}% | {current}/{total}',
  complete: '=',
  incomplete: '-'
});

const timer = setInterval(() => {
  bar.progress(Math.random() / 2);
}, 50);
bar.on('complete', () => {
  clearInterval(timer);
});
```

ratio(decimal[, tokens])

```js
const bar = new ProgressBar({
  width: 30,
  template: 'CLI Progress | {complete}{incomplete} | {percent}% | {current}/{total}Mb/s Chunks | Speed: {speed}Mb/s',
  complete: '\u2588',
  incomplete: '\u2591'
});

bar.render(0, {
  speed: 'N/A',
  current: 0,
  total: 0
});

const req = request('https://examples/download');

req.on('progress', (state) => {
  bar.ratio(state.percent, {
    total: (state.size.total / 1048576).toFixed(2),
    current: (state.size.transferred / 1048576).toFixed(2),
    speed: (state.speed / 1048576).toFixed(2)
  });
});
```

update(value[, tokens])

```js
const bar = new ProgressBar({
  width: 30,
  template: `CLI Progress | ${chalk.bgGreen('{complete}')}${chalk.bgWhite('{incomplete}')} | {percent}% | {current}/{total}`,
  complete: ' ',
  incomplete: ' '
});

let value = 0;
const timer = setInterval(() => {
  value += Math.round(Math.random() * 10);
  bar.update(value);
}, 50);
bar.on('complete', () => {
  clearInterval(timer);
});
```

### Options

These are keys in the options object you can pass to the progress bar along with `total` as seen in the example above.

* `current` - current completed value defaulting to `0`
* `total` - total number of ticks to complete defaulting to `100`
* `width` - the displayed width of the progress bar defaulting to `20`
* `stream` - the output stream defaulting to `process.stderr`
* `clear` - option to clear the bar on completion defaulting to `false`
* `complete` - completion character defaulting to `" "`
* `incomplete` - incomplete character defaulting to `" "`
* `template` - a template string defaulting to \``${chalk.bgGreen('{complete}')}${chalk.bgWhite('{incomplete}')} {percent}%`\`
* `done` - option to persist the logged output. Useful if you want to start a new log session below the current one. defaulting to `true`
* `showCursor` - option to show the cursor. Useful if a CLI accepts input from a user. defaulting to `false`

### Tokens

These are tokens you can use in the template of your progress bar.

* `{complete}` the complete progress bar
* `{incomplete}` the incomplete progress bar
* `{current}` current tick number
* `{total}` total ticks
* `{percent}` completion percentage

### Custom Tokens

You can define custom tokens by adding a {'name': value} object parameter to your method (update(), ratio(), increase(), progress(), etc.) calls.

```js
const bar = new ProgressBar(':current: :token1 :token2', { total: 3 })
bar.update(1, {
  'token1': "Hello",
  'token2': "World!"
});

bar.done();

bar.update(3, {
  'token1': "Goodbye",
  'token2': "World!"
});
```

The above example would result in the output below.

```bash
1: Hello World!
3: Goodbye World!
```

## Examples

* [render](/examples/sample)
* [increase value](/examples/increase)
* [increase ratio](/examples/progress)
* [update ratio](/examples/ratio)
* [update value](/examples/update)

## License

MIT

---
_Source: https://npm.io/package/cli-simple-progress · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._