repository·master·Indexed 20 days ago
https://github.com/privatenumber/cleyeAn intuitive command-line interface (CLI) development tool for Node.js. It provides a minimal API surface for parsing arguments and flags with strong typing, automatic help documentation generation, and support for sub-commands, custom flag types, and strict flag parsing.
Cleye automatically generates help documentation based on your cli() configuration. Users can view this documentation by passing the --help flag to your script.
$ node greet.js --help
greet.js
Usage:
greet.js [flags...] <first name> [last name]
Flags:
-h, --help Show help
--time <string> Time of day to greet (morning or evening) (default: "morning")Install the cleye package via npm to start developing command-line interfaces in Node.js.
npm i cleyeUse these common patterns to structure your Node.js CLI scripts with cleye:
cli({ name, parameters, flags }) for a simple script.command({ name, parameters, flags }, callback) to define a specific subcommand.commands option in cli({ commands: [cmd1, cmd2] }).async function as the callback to cli to handle asynchronous logic.process.argv.slice(2) as the final argument to cli to use custom input instead of the default.// Basic CLI
cli({ name, parameters, flags })
// Named command
command({ name, parameters, flags }, callback)
// Register commands
cli({ commands: [cmd1, cmd2] })
// Async callback
await cli({ ... }, async (argv) => { ... })
// Raw argv
cli({ ... }, callback, process.argv.slice(2))Cleye simplifies CLI development by handling argv parsing, providing strongly typed parameters and flags, and automatically generating --help documentation.
To use it, call the cli() function with a configuration object defining the script name, positional parameters, and flags.
import { cli } from 'cleye'
// Parse argv
const argv = cli({
name: 'greet.js',
// Define parameters using bracket notation:
// <name> for required, [name] for optional
parameters: [
'<first name>', // 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'
}
}
})
// Accessing parameters via argv._
const name = [argv._.firstName, argv._.lastName].filter(Boolean).join(' ')
// Accessing flags via argv.flags
if (argv.flags.time === 'morning') {
console.log(`Good morning ${name}!`)
} else {
console.log(`Good evening ${name}!`)
}When strictFlags: true is set in the cli() or command() configuration, the parser will throw an error if an unknown flag is provided (e.g., --baz when only --foo is defined).
cli({
flags: { foo: Boolean },
strictFlags: true
})
// --baz → Error: Unknown flag: --baz. (Did you mean --foo?)The render(nodes) method is the primary entry point for generating output. It recursively processes input which can be:
string.Array of nodes.HelpDocumentNode object: { type: string, data: any }.When a node object is encountered, the method looks up a method on the Renderers instance matching the type and calls it with data. If the type does not match a valid method, it throws an Error: Invalid node type: ....
Cleye handles --help and -h by default. You can customize or disable them.
help: false in the config. You can still call .showHelp() manually.version property. This also adds the version to the help documentation.--version flag, use help: { version: '...' }.cli({
version: '1.2.3'
})
// $ my-script --version
// 1.2.3cli({
version: '1.2.3'
})The help object allows you to customize the auto-generated help documentation. Setting a version in the cli() options automatically enables the --version flag.
description: A description of the tool.usage: A usage string (e.g., my-script [flags] <file>).examples: An array of usage examples.version: A version string to show in the help output.render: A function to customize how help nodes are rendered.Note: If you set help: false, auto-help handling is disabled, and you must call argv.showHelp() manually.
cli({
name: 'my-script',
version: '1.2.3',
help: {
description: 'Does things',
usage: 'my-script [flags] <file>',
examples: ['my-script foo.txt', 'my-script --output=dist foo.txt'],
version: '1.2.3'
}
})When defining the parameters array in your CliOptions, you can specify how arguments are treated using specific bracket syntax:
<name>. If the parameter is missing from the command line, the CLI will throw an error and show help.[name]. These do not trigger errors if omitted.... to the name inside the brackets, e.g., [...items]. This captures all remaining arguments into an array. Spread parameters must always be the last parameter defined.Constraints:
|, \, {, }, (, ), [, ], ^, $, +, *, ?, or ..// Example parameter definitions
const options = {
parameters: ['<id>', '[name]', '[...tags]']
};You can organize your CLI into subcommands by providing an array of command objects to the commands property in your CliOptions. Each command can have its own unique name, alias, flags, parameters, and callback function.
When a user runs my-cli <command>, the CLI identifies the command and executes its specific logic. The command inherits strictFlags and booleanFlagNegation from its parent if they are not explicitly set on the command itself.
import { cli } from 'cleye';
await cli({
name: 'app',
commands: [
{
name: 'init',
alias: 'i',
options: {
force: { type: 'boolean', description: 'Force initialization' }
},
callback: (parsed) => {
if (parsed.force) console.log('Forcing...');
}
}
]
});If you want to silently skip unknown flags instead of throwing an error, use the ignoreArgv option. The callback receives a type which can be 'known-flag', 'unknown-flag', or 'argument'. Returning true for 'unknown-flag' will cause the parser to ignore it.
cli({
ignoreArgv(type, flagOrArgv, value) {
if (type === 'unknown-flag') { return true }
}
})By default, boolean flags are set to false using the = operator (e.g., --verbose=false).
To support the --no-<flag> convention, set booleanFlagNegation: true in your cli() or command() configuration. This is additive: --verbose=false will still work. If both --verbose and --no-verbose are provided, the last one wins.
cli({
flags: { verbose: Boolean },
booleanFlagNegation: true
})
// --no-verbose → false
// --verbose=false → false