@kljj04/cli-kit

All-in-one terminal styling library for Node.js. Zero-dependency, fluent API for creating beautiful and interactive command-line interfaces. Supports RGB truecolor, gradients, boxes, tables, spinners, and progress bars.

Install

npm install @kljj04/cli-kit

Core Concept

All styling follows a consistent, chainable pattern:

const kit = require('@kljj04/cli-kit');

// Using a solid color
kit.color(R, G, B).style(...styles).context(value);

// Using a gradient
kit.gradient([R, G, B], [R, G, B]).style(...styles).context(value);

• .color(r, g, b): Sets a solid foreground color using RGB truecolor (0–255 each).
• .gradient([r,g,b], [r,g,b]): Sets a color gradient from a start color to an end color.
• .style(...args): Applies text styles and sets the output format.
• .context(value): Provides the content and renders the final output.

Text Styles

Pass any of these string arguments to .style() to apply text formatting. They can be combined.

Style	Description
bold	Bold text
dim	Dimmed text
italic	Italic text
underline	Underlined text
inverse	Inverts foreground/background colors
strikethrough	Strikethrough text

kit.color(200, 100, 255).style('bold', 'italic').context('Combined styles!');

---

Output Types

Pass one of the following arguments to .style() to define the output format. If no output type is specified, it defaults to print.

print (default)

Prints styled plain text to the console.

kit.color(255, 100, 50).style('bold').context('Hello, world!');
// is the same as:
kit.color(255, 100, 50).style('bold', 'print').context('Hello, world!');

box

Wraps the text content in a Unicode box. It automatically adjusts to the text width and supports multiline strings ( ).

kit.color(100, 200, 255).style('box').context('This is in a box.');
kit.color(150, 255, 100).style('bold', 'box').context('Line one
Line two');

┌───────────────────┐
│ This is in a box. │
└───────────────────┘
┌──────────┐
│ Line one │
│ Line two │
└──────────┘

spinner

Displays an animated spinner. This is useful for indicating long-running tasks. The .context() method returns a spinner object with a .stop() method.

const s = kit.color(0, 255, 200).style('spinner').context('Loading data...');

// After your async task is done
s.stop('Data loaded!'); // Stops the spinner and prints a final message.
// or
s.stop(); // Stops the spinner silently.

table

Generates a formatted table from an array of objects. The object keys are automatically used as table headers.

const data = [
    { module: 'Core', status: 'OK', version: '1.2.0' },
    { module: 'Network', status: 'OK', version: '1.1.0' },
    { module: 'Logger', status: 'Warn', version: '1.0.0' },
];

kit.color(200, 150, 255).style('table').context(data);

┌─────────┬────────┬─────────┐
│ module  │ status │ version │
┼─────────┼────────┼─────────┼
│ Core    │ OK     │ 1.2.0   │
│ Network │ OK     │ 1.1.0   │
│ Logger  │ Warn   │ 1.0.0   │
└─────────┴────────┴─────────┘

progress

Displays a progress bar. The .context() should be passed a number from 0 to 100.

kit.color(255, 200, 0).style('progress').context(75);
// [██████████████████████░░░░░░] 75%

Live Progress Bars

To create a progress bar that updates on the same line, add the 'override' style.

let percentage = 0;
const interval = setInterval(() => {
    percentage++;
    kit.color(0, 255, 150).style('progress', 'override').context(percentage);
    if (percentage >= 100) {
        clearInterval(interval);
        // The 'override' style automatically adds a newline when 100% is reached.
    }
}, 30);

Gradient Progress Bars

Use .gradient() instead of .color() to create a progress bar with a smooth color transition. The gradient is calculated in the perceptually uniform OKLCH color space for superior visual quality.

kit.gradient([255, 0, 0], [0, 255, 255]).style('progress').context(50);

You can also use gradients with live progress bars. For the best visual effect, add the 'fixedgradient' style.

• Default Gradient: The gradient range grows with the progress. At 50% progress, you only see the first half of the gradient's colors.
• 'fixedgradient': The full gradient is mapped across the entire width of the bar from the start. Progress is shown by "revealing" the colored bar from left to right.

// Live progress bar with a fixed gradient
let i = 0;
const iv = setInterval(() => {
    i++;
    kit.gradient([255, 0, 0], [0, 255, 255])
       .style('progress', 'override', 'fixedgradient')
       .context(i);
    if (i >= 100) clearInterval(iv);
}, 50);

License

MIT