cliui 9.x

Complete instructions

Verified against cliui@9.0.1 on 2026-09-08. 7 of 7 examples executed.

cliui

Version and module format

^9.0.0 resolves to 9.0.1. The package is published as ESM and its package metadata requires Node >=20. Use the documented default import:

import assert from "node:assert/strict";
import cliui from "cliui";

const ui = cliui({});
ui.div("Usage: $0 [command] [options]");

assert.equal(typeof ui.toString(), "string");
assert.match(ui.toString(), /Usage: \$0/);

Do not copy the commonly seen v8 shape:

const ui = require('cliui')()

Version 9 moved to ESM. Version 9.0.1 fixed require("cliui") for CommonJS, but the package remains published with ESM metadata and the documented v9 usage is import cliui from "cliui".

Create and configure a UI

Pass an options object to the factory. The documented options include width and wrap.

import assert from "node:assert/strict";
import cliui from "cliui";

const ui = cliui({ width: 30, wrap: true });
ui.div("A line in a configured UI");

assert.equal(typeof ui.toString(), "string");
assert.match(ui.toString(), /A line in a configured UI/);

Rows and columns with div

ui.div(...) creates a row. Arguments can be strings or column objects. Column objects support text, width, align, padding, and border.

import assert from "node:assert/strict";
import cliui from "cliui";

const ui = cliui({});
ui.div(
  {
    text: "-f, --file",
    width: 20,
    padding: [0, 4, 0, 4]
  },
  {
    text: "the file to load.",
    width: 20
  },
  {
    text: "[required]",
    align: "right"
  }
);

const output = ui.toString();
assert.match(output, /-f, --file/);
assert.match(output, /the file to load\./);
assert.match(output, /\[required\]/);

A string argument is also valid as a column or complete row:

import assert from "node:assert/strict";
import cliui from "cliui";

const ui = cliui({});
ui.div("first column", "second column");

const output = ui.toString();
assert.match(output, /first column/);
assert.match(output, /second column/);

Single-string layout DSL

When a single string is passed to ui.div, the string has layout markers:

• \n creates a new row.
• \t creates a new column.
• \s creates padding.

import assert from "node:assert/strict";
import cliui from "cliui";

const ui = cliui({ width: 60 });
ui.div(
  "Usage: node ./bin/foo.js\n" +
  "  <regex>\t  provide a regex\n" +
  "  <glob>\t  provide a glob\t [required]"
);

const output = ui.toString();
assert.match(output, /Usage: node \.\/bin\/foo\.js/);
assert.match(output, /<regex>/);
assert.match(output, /provide a regex/);
assert.match(output, /<glob>/);
assert.match(output, /\[required\]/);

Append with span

ui.span(...) appends the next row without creating a new line. It accepts the same string and column forms documented for layout rows.

import assert from "node:assert/strict";
import cliui from "cliui";

const ui = cliui({});
ui.div("left");
ui.span("right");

const output = ui.toString();
assert.match(output, /left/);
assert.match(output, /right/);
assert.ok(output.indexOf("left") < output.indexOf("right"));

Reset accumulated output

ui.resetOutput() resets the UI elements while maintaining the configured width and wrap settings.

import assert from "node:assert/strict";
import cliui from "cliui";

const ui = cliui({ width: 40, wrap: true });
ui.div("content before reset");
assert.match(ui.toString(), /content before reset/);

ui.resetOutput();
assert.equal(ui.toString(), "");

ui.div("content after reset");
assert.match(ui.toString(), /content after reset/);

What this skill does not cover

• Exact rendering rules for every combination of width, wrapping, alignment, padding, and borders.
• The complete set of accepted values or semantics for each column option.
• Package internals, TypeScript compilation, or repository development scripts.
• CLI invocation: the research documents cliui as a programmatic UI-string builder, not as a package-owned command-line runner.
• Runtime behavior outside the documented Node >=20 environment.