Installation

Documentation

@munesoft/cli-ui

Beautiful CLI spinners, progress bars, and task displays with zero setup.

⠹ Compiling TypeScript…
  ✔ Download assets
  ✔ Bundle JavaScript
  ⚠ Optimise images (2 already optimal)
  ○ Deploy CDN

Why cli-ui?

Most CLI tools look static and lifeless. cli-ui gives your scripts clean, animated terminal UX with a single import — no config, no dependencies.

| Feature | ora | cli-progress | cli-ui | | ------------------ | :-: | :----------: | :--------: | | Spinners | ✅ | ❌ | ✅ | | Progress bars | ❌ | ✅ | ✅ | | Multi-task display | ❌ | ❌ | ✅ | | Async task runner | ❌ | ❌ | ✅ | | TypeScript types | ✅ | ✅ | ✅ | | Zero dependencies | ❌ | ❌ | ✅ |

Installation

npm install @munesoft/cli-ui

Quick start

import { spinner, progress, tasks, run } from "@munesoft/cli-ui";

API

spinner(label, options?)

Animated terminal spinner with four terminal states.

import { spinner } from "@munesoft/cli-ui";

const spin = spinner("Loading...");
spin.start();

// update label on the fly
spin.update("Still loading...");

// resolve with one of four states
spin.success("Done!");    // ✔ green
spin.error("Failed!");    // ✖ red
spin.warn("Watch out!");  // ⚠ yellow
spin.stop();              // silent clear

Options

| Option | Type | Default | Description | | ------- | -------- | -------- | ------------------------------------------------------------ | | style | string | "dots" | "dots" · "line" · "pulse" | | color | string | "cyan" | "cyan" · "green" · "red" · "yellow" · "magenta" |

Styles

spinner("Loading...", { style: "dots"  }); // ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏  (default)
spinner("Loading...", { style: "line"  }); // - \ | /
spinner("Loading...", { style: "pulse" }); // █ ▓ ▒ ░ ▒ ▓

Colors

spinner("Loading...", { color: "cyan"    }); // default
spinner("Loading...", { color: "green"   });
spinner("Loading...", { color: "red"     });
spinner("Loading...", { color: "yellow"  });
spinner("Loading...", { color: "magenta" });

progress(options?)

A live-updating terminal progress bar.

import { progress } from "@munesoft/cli-ui";

const bar = progress({ total: 100, label: "Building" });

bar.update(25);          // [████████░░░░░░░░░░░░░░░░░░░░░░]  25%  25/100
bar.update(75);          // [██████████████████████░░░░░░░░]  75%  75/100
bar.increment(10);       // increment by step instead of absolute value
bar.complete("Build finished");

Options

| Option | Type | Default | Description | | ------- | -------- | -------- | ----------------------------------- | | total | number | 100 | Value that represents 100% | | width | number | 30 | Visual bar width in characters | | color | string | "cyan" | Fill colour (same options as above) | | label | string | "" | Text printed before the bar |

Methods

| Method | Description | | ------------------- | ------------------------------------------------- | | .update(n) | Set current value (absolute) | | .increment(step?) | Add step to current value (default 1) | | .complete(msg?) | Jump to 100%, add optional done message, newline | | .value | Read current value | | .totalValue | Read configured total |

tasks()

Live multi-task display — track many async jobs at once, each with its own status icon.

import { tasks } from "@munesoft/cli-ui";

const t = tasks();

// register all tasks up front (shows them as pending ○)
t.add("Download data");
t.add("Process files");
t.add("Upload results");

// control each task manually
t.start("Download data");                    // ⠹ animated spinner
// ... do work ...
t.success("Download data");                  // ✔ green
t.error("Process files", "ENOMEM");          // ✖ red with inline message
t.warn("Upload results", "Slow connection"); // ⚠ yellow

Automatic async runner

const t = tasks();

// tasks().run() handles start → success/error automatically
await t.run("Build project", async () => {
  await build();
});

await t.run("Deploy", async () => {
  await deploy();
});

Methods

| Method | Description | | ------------------------- | ---------------------------------------------------- | | .add(name) | Register a task as pending ○ | | .start(name) | Mark as running with animated spinner | | .success(name, label?) | Mark as success ✔ with optional label override | | .error(name, errorMsg?) | Mark as error ✖ with optional inline error message | | .warn(name, label?) | Mark as warn ⚠ with optional label override | | .run(name, asyncFn) | Auto-managed task: start → success or error |

All methods are chainable: t.add("a").add("b").add("c").

run(label, fn, options?)

Convenience wrapper — run a single async function under a spinner, no boilerplate.

import { run } from "@munesoft/cli-ui";

// resolves to fn's return value on success
const data = await run("Fetching config", async () => {
  return await fetchConfig();
});

// spinner automatically shows error state on throw
await run("Risky operation", async () => {
  await riskyThing(); // if this throws → ✖ error message shown
});

// supports the same options as spinner()
await run("Building", build, { style: "line", color: "magenta" });

Silent mode (CI environments)

Set CLI_UI_SILENT=true to suppress all output. All functions still work correctly — they just produce no terminal output.

CLI_UI_SILENT=true node deploy.js

process.env.CLI_UI_SILENT = "true"; // or set programmatically

TypeScript

Full TypeScript support is included — no @types/ package needed.

import { spinner, progress, tasks, run } from "@munesoft/cli-ui";
import type { Spinner, ProgressBar, Tasks, SpinnerOptions } from "@munesoft/cli-ui";

const opts: SpinnerOptions = { style: "dots", color: "cyan" };
const spin: Spinner = spinner("Loading", opts);

Examples

Run the included examples:

node examples/demo.js       # full feature showcase
node examples/spinner.js    # spinner styles, states, colors
node examples/progress.js   # progress bar variants
node examples/tasks.js      # multi-task display

Requirements

• ◆Node.js ≥ 14.0.0
• ◆ESM ("type": "module" in your package.json, or use .mjs extension)

License

MIT © Munesoft