cleye
The intuitive command-line interface (CLI) development tool.
### Features
- Minimal API surface
- Powerful flag parsing
- Strongly typed parameters and flags
- Command support
- Help documentation generation (customizable too!)
→ [Try it out online](https://stackblitz.com/edit/cleye-demo?devtoolsheight=50&file=examples/greet.ts&view=editor)
Already a sponsor? Join the discussion in the Development repo!
## Install
```bash
npm i cleye
```
## About
_Cleye_ makes it very easy to develop command-line scripts in Node.js. It handles argv parsing to give you strongly typed parameters + flags and generates `--help` documentation based on the provided information.
Here's an example script that simply logs: `Good morning/evening !`:
_greet.js:_
```ts
import { cli } from 'cleye'
// Parse argv
const argv = cli({
name: 'greet.js',
// Define parameters
parameters: [
'', // First name is required
'[last name]' // Last name is optional
],
// Define flags/options
flags: {
// Parses `--time` as a string
time: {
type: String,
description: 'Time of day to greet (morning or evening)',
default: 'morning'
}
}
})
const name = [argv._.firstName, argv._.lastName].filter(Boolean).join(' ')
if (argv.flags.time === 'morning') {
console.log(`Good morning ${name}!`)
} else {
console.log(`Good evening ${name}!`)
}
```
🛠 In development, type hints are provided on parsed flags and parameters:
Type hints for Cleye's output are very verbose and readable
📖 Generated help documentation can be viewed with the `--help` flag:
```sh
$ node greet.js --help
greet.js
Usage:
greet.js [flags...] [last name]
Flags:
-h, --help Show help
--time Time of day to greet (morning or evening) (default: "morning")
```
✅ Run the script to see it in action:
```sh
$ node greet.js John Doe --time evening
Good evening John Doe!
```
## Examples
Want to dive right into some code? Check out some of these examples:
- [**greet.js**](/examples/greet/index.ts): Working example from above
- [**npm install**](/examples/npm/index.ts): Reimplementation of [`npm install`](https://docs.npmjs.com/cli/install/)'s CLI
- [**tsc**](/examples/tsc/index.ts): Reimplementation of TypeScript [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html)'s CLI
- [**snap-tweet**](/examples/snap-tweet/index.ts): Reimplementation of [`snap-tweet`](https://github.com/privatenumber/snap-tweet)'s CLI
- [**pkg-size**](/examples/pkg-size/index.ts): Reimplementation of [`pkg-size`](https://github.com/pkg-size/pkg-size)'s CLI
## Usage
### Arguments
Arguments are values passed into the script that are not associated with any flags/options.
For example, in the following command, the first argument is `file-a.txt` and the second is `file-b.txt`:
```
$ my-script file-a.txt file-b.txt
```
Arguments can be accessed from the `_` array-property of the returned object.
Example:
```ts
const argv = cli({ /* ... */ })
// $ my-script file-a.txt file-b.txt
argv._ // => ["file-a.txt", "file-b.txt"] (string[])
```
#### Parameters
Parameters (aka _positional arguments_) are the names that map against argument values. Think of parameters as variable names and arguments as values associated with the variables.
Parameters can be defined in the `parameters` array-property to make specific arguments accessible by name. This is useful for writing more readable code, enforcing validation, and generating help documentation.
Parameters are defined in the following formats:
- **Required parameters** are indicated by angle brackets (eg. ``).
- **Optional parameters** are indicated by square brackets (eg. `[parameter name]`).
- **Spread parameters** are indicated by `...` suffix (eg. `` or `[parameter name...]`).
Note, required parameters cannot come after optional parameters, and spread parameters must be last.
Parameters can be accessed in camelCase on the `_` property of the returned object.
Example:
```ts
const argv = cli({
parameters: [
'',
'[optional parameter]',
'[optional spread...]'
]
})
// $ my-script a b c d
argv._.requiredParameter // => "a" (string)
argv._.optionalParameter // => "b" (string | undefined)
argv._.optionalSpread // => ["c", "d"] (string[])
```
#### End-of-flags
End-of-flags (`--`) (aka _end-of-options_) allows users to pass in a subset of arguments. This is useful for passing in arguments that should be parsed separately from the rest of the arguments or passing in arguments that look like flags.
An example of this is [`npm run`](https://docs.npmjs.com/cli/v8/commands/npm-run-script):
```sh
$ npm run