cli-cursor

library5.0.0jsnpmunverified

cli-cursor is a lightweight utility that provides a simple API for showing, hiding, and toggling the command-line interface cursor. Its primary function is to manage cursor visibility in terminal applications, with a notable feature of gracefully restoring the cursor's state upon process exit, preventing a permanently hidden cursor. The current stable version is 5.0.0, which requires Node.js 18 or higher. Releases are typically driven by updates to Node.js LTS versions and the transition to pure ESM, rather than a fixed cadence. Key differentiators include its robust cursor restoration mechanism (powered by `restore-cursor`) and a minimalist, focused API, making it a reliable choice for CLI tools needing precise cursor control.

devops

npm install cli-cursor

github ↗package ↗

INSTALL

IMPORT

SIG · CLI-CURSOR

cli-cursor

devopsjavascriptv5.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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.

cliCursor

✓ import cliCursor from 'cli-cursor';

✗ const cliCursor = require('cli-cursor');

Since v4.0.0, this package is pure ESM and must be imported using `import`. CommonJS `require()` is not supported.

cliCursor.hide

✓ import cliCursor from 'cli-cursor'; cliCursor.hide();

✗ import { hide } from 'cli-cursor';

The API methods (`hide`, `show`, `toggle`) are properties of the default exported object, not named exports.

cliCursor.toggle

✓ import cliCursor from 'cli-cursor'; cliCursor.toggle(true);

The `toggle` method accepts an optional `force` boolean argument to explicitly show or hide the cursor, and an optional `stream`.

Demonstrates hiding and toggling the CLI cursor, with graceful restoration on exit and explicit showing before the application terminates.

import cliCursor from 'cli-cursor'; import process from 'node:process'; console.log('Cursor is visible. Hiding now...'); cliCursor.hide(); // Simulate some work setTimeout(() => { console.log('Performing some background task...'); }, 1000); // Toggle cursor visibility based on a condition const shouldShowCursor = process.env.SHOW_CURSOR === 'true'; setTimeout(() => { console.log(`Toggling cursor to ${shouldShowCursor ? 'visible' : 'hidden'}...`); cliCursor.toggle(shouldShowCursor); // Ensure cursor is shown before exiting in case of manual toggle logic // This is handled gracefully by `restore-cursor` on process exit, but explicit is sometimes clearer. setTimeout(() => { cliCursor.show(); // Ensure cursor is visible before application ends console.log('Cursor should now be visible. Exiting.'); }, 1500); }, 2000);

Debug

Known issues

breakingVersion 5.0.0 of `cli-cursor` requires Node.js 18 or higher. Projects running on older Node.js versions will encounter compatibility issues.

fix

Upgrade Node.js to version 18 or higher, or pin `cli-cursor` to a compatible older version (e.g., `^4.0.0` for Node.js 12.20+).

affects: >=5.0.0

breaking`cli-cursor` became a pure ESM package in version 4.0.0. This means it no longer supports CommonJS `require()` syntax.

fix

Migrate your project to use ES modules (`import`) or dynamically import the package. If using CommonJS, pin `cli-cursor` to `^3.1.0`.

affects: >=4.0.0

breakingVersion 4.0.0 of `cli-cursor` requires Node.js 12.20 or higher. Running on older Node.js versions will result in runtime errors.

fix

Upgrade Node.js to version 12.20 or higher, or downgrade `cli-cursor` to `^3.1.0` if Node.js 8+ is required.

affects: >=4.0.0 <5.0.0

breakingVersion 3.0.0 introduced a minimum Node.js requirement of 8. This might break projects on very old Node.js runtimes.

fix

Upgrade Node.js to version 8 or higher, or use `cli-cursor@^2.x.x`.

affects: >=3.0.0 <4.0.0

gotchaWhile `cli-cursor` gracefully restores the cursor on process exit, unexpected termination (e.g., `kill -9`) might leave the cursor hidden. It's good practice to ensure `cliCursor.show()` is called before explicit application termination if you hide it.

fix

Include `cliCursor.show()` in your application's cleanup logic, especially before process exits that might not trigger `restore-cursor`'s hooks.

affects: all

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to `require()` `cli-cursor` in a CommonJS module after version 4.0.0, which is pure ESM.

fix

Change `const cliCursor = require('cli-cursor');` to `import cliCursor from 'cli-cursor';` and ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json` or using `.mjs` extension).

TypeError: cliCursor.hide is not a function

Incorrectly importing `hide` or other methods as named exports instead of accessing them from the default exported object.

fix

Ensure you are using `import cliCursor from 'cli-cursor';` and then calling `cliCursor.hide()`, `cliCursor.show()`, or `cliCursor.toggle()`.

Error [ERR_UNSUPPORTED_DIR_IMPORT]: Named export 'default' not found. The requested module 'cli-cursor' is an ECMAScript module, and does not provide a default export.

This error can occur if a bundler or specific import configuration misinterprets the default export, or if an older environment has issues with ESM interoperability. Sometimes this happens with incorrect TypeScript `esModuleInterop` settings or when mixing CJS and ESM without proper transpilation.

fix

Verify your `tsconfig.json` includes `"esModuleInterop": true`, `"allowSyntheticDefaultImports": true`, and ensure your bundler (if any) is configured correctly for ESM. Alternatively, try `import * as cliCursor from 'cli-cursor';` though `import cliCursor from 'cli-cursor';` should work for a default export.

SyntaxError: Cannot use import statement outside a module

Attempting to use `import` syntax in a file that is treated as a CommonJS module (e.g., a `.js` file without `"type": "module"` in `package.json`, or a `.cjs` file).

fix

Either rename your file to `.mjs`, add `"type": "module"` to your `package.json`, or configure your build system (e.g., Babel, TypeScript) to transpile ESM to CommonJS if your runtime environment is strictly CommonJS.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

restore-cursorrequiredHandles the graceful restoration of the CLI cursor upon process exit, preventing it from remaining hidden.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/sindresorhus/cli-cursor ↗

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