cli-width

library4.1.0jsnpmunverified

cli-width is a JavaScript utility for Node.js environments that accurately determines the current width of the stdout window. It employs a robust fallback mechanism, checking `tty` information, `output.columns` property, a custom `CLI_WIDTH` environment variable, and finally a configurable default width. The package is currently stable at version 4.1.0 and is actively maintained, with releases occurring as needed for bug fixes or minor enhancements. It is designed to be lightweight and provides TypeScript types out-of-the-box, making it suitable for modern Node.js projects that require responsive command-line interfaces. Its primary differentiator is the comprehensive fallback strategy to ensure a width is always returned.

devops

github ↗package ↗

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

The package exports the `cliWidth` function as its default export. While TypeScript might sometimes allow named import, the intended usage is a default import.

import cliWidth from 'cli-width';

This is the standard CommonJS `require` syntax for Node.js environments. The package is compatible with both CJS and ESM.

const cliWidth = require('cli-width');

For type-only imports in TypeScript, use `import type` to ensure no runtime code is generated.

import type { Options } from 'cli-width';

This quickstart demonstrates how to get the CLI width with default settings, and how to configure it with custom options for default width, output stream, and tty module. It also shows how the `CLI_WIDTH` environment variable can influence the detected width.

import cliWidth, { Options } from 'cli-width'; import * as process from 'process'; // Get the current CLI width with default fallbacks const currentWidth = cliWidth(); console.log(`Current CLI width: ${currentWidth}`); // Define custom options for fallback behavior const customOptions: Options = { defaultWidth: process.env.DEFAULT_CLI_WIDTH ? parseInt(process.env.DEFAULT_CLI_WIDTH, 10) : 80, output: process.stdout, tty: require('tty'), // Use the built-in tty module }; // Get CLI width with custom options const customWidth = cliWidth(customOptions); console.log(`CLI width with custom options: ${customWidth}`); // Example of setting an environment variable to test CLI_WIDTH fallback process.env.CLI_WIDTH = '120'; const envVarWidth = cliWidth(); console.log(`CLI width with CLI_WIDTH env var: ${envVarWidth}`); // Clean up environment variable for subsequent tests delete process.env.CLI_WIDTH;

Debug

Known footguns

breakingThe way options are passed to `cliWidth` changed significantly in v2.0.0. Previously, options might have been positional or less structured. Now, all configuration must be passed via a single `options` object as the first argument.

gotchaWhen running in non-TTY environments (e.g., piped output, CI/CD without TTY emulation), `cli-width` might return the `defaultWidth` or `0` if not explicitly configured. This is expected behavior as there's no terminal to query for dimensions.

gotchaThe `tty` module fallback relies on `require('tty')`. In environments where the `tty` module is not available or behaves unexpectedly (e.g., some browser bundlers trying to shim Node built-ins), this fallback might fail. Ensure your target environment is Node.js.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

14 hits · last 30 days

gptbot

ahrefsbot

bytedance

script

bingbot

Resources

githubhttps://github.com/knownasilya/cli-width ↗

packagehttps://www.npmjs.com/package/cli-width ↗