# cli-er
> Tool for building advanced type-safe cli applications
Latest version **0.21.2** (published 2026-07-10) · MIT license · 0 weekly downloads
## Install
```sh
npm install cli-er
pnpm add cli-er
yarn add cli-er
bun add cli-er
```
## Health
**Score 70/100 (B)** — status: active.
Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.
Warnings: low downloads; no esm support; pre 1.0.
## Facts
| | |
|---|---|
| Version | 0.21.2 |
| Published | 2026-07-10 |
| First published | 2022-08-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=12 |
| Dependencies | 0 |
| Unpacked size | 53.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 5 |
| Author | Carlos Cortón Cobas |
| Maintainers | carloscortonc |
| Keywords | cli, command, nodejs, parser |
## Links
- npm: https://www.npmjs.com/package/cli-er
- Repository: https://github.com/carloscortonc/cli-er
- Homepage: https://github.com/carloscortonc/cli-er#readme
- Issues: https://github.com/carloscortonc/cli-er/issues
- npm.io page: https://npm.io/package/cli-er
## Alternatives
- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads
## Recent versions
- 0.21.2 (latest) — 2026-07-10
- 0.21.1 — 2026-07-07
- 0.21.0 — 2026-07-04
- 0.20.0 — 2026-06-13
- 0.19.1 — 2026-06-08
- 0.19.0 — 2026-01-15
- 0.18.2 — 2026-01-10
- 0.18.1 — 2025-10-04
- 0.18.0 — 2025-09-26
- 0.17.0 — 2025-09-02
- 0.16.0 — 2024-09-21
- 0.15.0 — 2024-03-10
- 0.14.0 — 2023-12-24
- 0.13.0 — 2023-10-18
- 0.12.1 — 2023-09-20
- … 19 more at https://npm.io/package/cli-er/versions
## README
cli-er
Tool for building advanced type-safe CLI applications using a definition object.
Implements a folder structure strategy that helps organize all the logic, also including help-generation.
_cli.js_:
```js
import Cli from "cli-er";
const definition = {...}
new Cli(definition).run();
```
Invocation:
```
node cli.js [namespace(s)|command] [OPTIONS]
```
## Features
- [**Help generation**](https://carloscortonc.github.io/cli-er/docs/guide/features#help-generation): help is generated for all commands and options.
- [**Routing**](https://carloscortonc.github.io/cli-er/docs/guide/features#routing): routes are generated where command handlers are expected to be found.
- [**Configuration file support**](https://carloscortonc.github.io/cli-er/docs/guide/features#configuration-file-support): define the list of configuration file-names for your cli, and `cli-er` will try to find (from `process.cwd()` up), read its contents, and use it inside [`Cli.run`](https://carloscortonc.github.io/cli-er/docs/reference/api#runargs).
- [**Lifecycle hooks**](https://carloscortonc.github.io/cli-er/docs/guide/features#lifecycle-hooks): execute code on lifecycle events when using `Cli.run()` (beforeParse, afterParse, beforeExecute, afterExecute).
- [**Plugins**](https://carloscortonc.github.io/cli-er/docs/guide/features#plugins): define reusable logic with a set of hooks.
- [**Environment-variable prefix support**](https://carloscortonc.github.io/cli-er/docs/guide/features#environment-variable-prefix-support): define a prefix so all environment variables matching that will be passed into [`Cli.run`](https://carloscortonc.github.io/cli-er/docs/reference/api#runargs).
- [**Reading from stdin**](https://carloscortonc.github.io/cli-er/docs/guide/definition#reading-from-stdin): configure options whose value can be provided from stdin.
- [**Intl support**](https://carloscortonc.github.io/cli-er/docs/guide/features#intl-support): support for internationalized messages.
- [**Bash completion**](https://carloscortonc.github.io/cli-er/docs/guide/features#bash-completion): a command is created to generate the `bash-completions` script for the cli.
- [**Debug logger**](https://carloscortonc.github.io/cli-er/docs/guide/features#debug-logger): static debug-logging utility.
- [**Debug mode**](https://carloscortonc.github.io/cli-er/docs/guide/features#debug-mode): validate the definition and options, especially when upgrading to a new version.
- [**Typescript support**](https://carloscortonc.github.io/cli-er/docs/guide/features#typescript-support): build the cli with typescript.
#### Example
Given the following definition (docker.js):
```js
const definition = {
builder: {
description: "Manage builds",
options: {
build: {
description: "Build an image from a Dockerfile",
options: {
source: {
positional: 0,
required: true,
description: "Path or Url to the Dockerfile"
}
}
},
},
},
debug: {
type: "boolean",
aliases: ["D", "debug"],
default: false,
},
};
```
it will allow us to structure the code as follows:
```sh
.
├─ docker.js
└─ builder
└── build.js
```
so we can then execute:
```
node docker.js builder build . -- someother-external-option
```
which will try to invoke, in order:
1. `/builder/build/index.js`
2. `/builder/build.js`
3. `/builder/index.js`
4. `/builder.js`
5. `/index.js`
6. `/docker.js`
with the parsed options (only the first two are default imports, the rest are named imports using the command name, in this case `build`).
This allows us to organize and structure the logic nicely.
You can check the full [docker-based example](./examples/docker) for a more in-depth demo.
## Installation
```sh
npm install cli-er
```
## Usage
`cli-er` default-exports a class, which takes in a [definition object](https://carloscortonc.github.io/cli-er/docs/guide/definition) and an optional argument [CliOptions](https://carloscortonc.github.io/cli-er/docs/reference/cli-options). The available methods are the following:
- [**parse(args)**](https://carloscortonc.github.io/cli-er/docs/reference/api#parseargs): parse the given arguments and return an object containing the options, errors and calculated location.
- [**run(args?)**](https://carloscortonc.github.io/cli-er/docs/reference/api#runargs): parse the given arguments and execute the corresponding script found in the calculated location. Integrates help and version generation.
- [**help(location?)**](https://carloscortonc.github.io/cli-er/docs/reference/api#helplocation): generate help based on the definition. Can be scoped to a namespace/command.
- [**version()**](https://carloscortonc.github.io/cli-er/docs/reference/api#version): generate a formatted version of the application's version.
- [**completions()**](https://carloscortonc.github.io/cli-er/docs/reference/api#completions): output bash-completion script contents.
- [**configContent()**](https://carloscortonc.github.io/cli-er/docs/reference/api#configcontent): find the contents of configuration files (e.g. `.prettierrc.json`).
- [**envContent()**](https://carloscortonc.github.io/cli-er/docs/reference/api#envcontent): find the contents of configuration files (e.g. `.prettierrc.json`).
#### Glossary
- **Namespace**: is used to group commands, but cannot be invoked. Can contain other namespaces, commands or options.
- **Command**: Is the final invocable element. Can only contain options.
- **Option**: arguments that hold values of different types, like string, boolean, list...
---
_Source: https://npm.io/package/cli-er · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._