@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