Cross-Platform CLI for Terminal Output

2.0.0 · active · verified Wed Apr 22

echo-cli is a utility designed to address inconsistencies in command-line output across different operating systems, particularly focusing on the limitations of Windows CMD regarding escape sequences and newline characters. It provides a cross-platform solution for outputting text to the terminal, supporting all standard JavaScript escape sequences. This makes it particularly useful for `npm scripts` and other automation tasks where consistent terminal output, including formatted text and newlines, is crucial regardless of the underlying shell. The current stable version is 2.0.0, released after dropping a dependency on `meow`. The package does not have a defined public release cadence but is actively maintained to ensure its core functionality.

Common errors

```
echo-cli: command not found
```
cause The `echo-cli` command-line tool is not installed globally or is not accessible in the current shell's PATH.

fix To use it globally: `npm install -g echo-cli`. To use it as a `devDependency` in `npm scripts` (recommended): `npm install --save-dev echo-cli`. Ensure your `package.json` scripts reference it correctly.
```
Escape sequences like \n or \t are printed literally, not interpreted.
```
cause The shell is interpreting the escape sequence before `echo-cli` receives the argument, or `echo-cli` isn't correctly parsing it.

fix Ensure the text containing escape sequences is enclosed in quotes, e.g., `echo-cli "Line 1\nLine 2"`. This prevents the shell from processing them prematurely.

Warnings

breaking Version 2.0.0 removed the `meow` dependency. While this was an internal change, it could potentially lead to minor, non-functional output differences in edge cases due to the change in input parsing logic.
Fix: No direct fix needed for consumers; simply update to v2.0.0. Review any scripts that rely on highly specific output formatting if issues arise.
gotcha When using escape sequences (e.g., `\n`, `\t`) in shell commands, it is crucial to wrap the entire string in quotes (preferably double quotes) to prevent the shell from interpreting the escape sequences itself before `echo-cli` can process them.
Fix: Always quote strings containing escape sequences: `echo-cli "Hello,\nworld!"` instead of `echo-cli Hello,\nworld!`
gotcha The primary purpose of `echo-cli` is to provide consistent output on Windows CMD, which notoriously lacks support for standard escape sequences and handles newlines differently than Bash. For non-Windows environments, the native `echo` command often suffices, but `echo-cli` ensures cross-platform consistency.
Fix: Utilize `echo-cli` specifically in environments or scripts where cross-platform consistency of escape sequences and newline handling is paramount, especially when targeting Windows CMD.

Install

npm install echo-cli npm
yarn add echo-cli yarn
pnpm add echo-cli pnpm

Imports

echo-cli command
wrong:
```
import echoCli from 'echo-cli';
```
correct:
```
echo-cli "Hello, world!\nThis is a new line."
```
This package is a command-line interface (CLI) tool and does not expose a programmatic API for direct import into JavaScript/TypeScript applications. Its functionality is accessed by executing the `echo-cli` command in a shell or within `npm scripts`.
Type (none)
wrong:
```
import type { EchoOptions } from 'echo-cli';
```
correct:
```
// No direct type imports as this is a CLI.
```
As `echo-cli` is primarily a CLI without a programmatic API, there are no specific types or interfaces intended for programmatic import or use within TypeScript code.
echo-cli (CommonJS)
wrong:
```
const echoCli = require('echo-cli');
```
correct:
```
/* Use via child_process.exec or similar for programmatic execution */
```
Attempting to `require('echo-cli')` will likely return a reference to the CLI executable's entry point, not a library function. For programmatic execution in Node.js, use `child_process.exec` or `spawn` to run the command.

Quickstart

Demonstrates `echo-cli` usage within `package.json` scripts to output formatted messages with escape sequences before and after build tasks, ensuring consistent output across platforms.

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "prebuild": "echo-cli 'Starting build process...\n'",
    "build": "npm run prebuild && echo-cli 'Compiling code...\t(This might take a moment)' && sleep 1 && echo-cli '\nBuild complete! 🎉'",
    "test": "echo-cli 'Running tests...\n' && npm test"
  },
  "devDependencies": {
    "echo-cli": "^2.0.0"
  }
}

view raw JSON →