Declarative CLI parsing for node apps
npm install cliparse

This is a library designed to express command-line options. It supports
commands and subcommands (at an arbitrary depth), automatically generates help
text and usage contents. You can use custom parsers for attributes and
options values (types supported out of the box: int, bool, string).
Its design is vaguely inspired from
optparse-applicative
which is a great CLI parsing library. JS being not as expressive as Haskell, a
direct port is not possible.
> Disclaimer:
>
> This library has been started by @divarvel as part of his job at Clever Cloud. Since he
> left the company and doesn't use cliparse nor wishes to maintain it anymore, we
> mutually agreed to transfer ownership of the project to CleverCloud.
>
> Big thanks to him for producing this library!
``bash`
npm install cliparse
`javascript
#!/usr/bin/env node
var cliparse = require("cliparse");
var parsers = cliparse.parsers;
function echoModule(params) {
}
function addModule(params) {
}
var cliParser = cliparse.cli({
name: "my-executable",
description: "Simple CLI written for the sake of the example",
commands: [
cliparse.command(
"echo",
{ description: "Display the given value",
args: [ cliparse.argument("value", { description: "Simple value" })],
options: [ cliparse.flag("reverse", { aliases: ["r"], description: "Reverse the value"}) ]
},
echoModule),
cliparse.command(
"add2",
{ description: "Add 2 to the given integer and display the result",
args: [
cliparse.argument("int",
{ default: 0,
parser: parsers.intParser,
description: "Int to add 2 to" })
]
},
addModule)
]
});
cliparse.parse(cliParser);
`
Where echoModule and addModule are callbacks taking a { args: ['value'], options: {key: 'value'} } parameter.
#### Top-level help
`
$ my-executable --help
Usage: my-executable
Simple CLI written for the sake of the example.
Options:
[--help, -?] Display help about this program
Available commands:
help Display help about this program
echo VALUE Display the given value
add2 [INT] Add 2 to the given integer and display the result
`
#### Command-level help
`
$ my-executable echo --help
Usage : my-executable echo VALUE
display the given value
Arguments:
VALUE Simple value
Options:
[--help, -?] Display help about this program
[--reverse, -r] Reverse the value
`
The command constructor takes an optional commands attribute which allows
you to nest subcommands at an arbitrary level.
`javascript`
var testCli = cliparse.cli({
name: "testCli",
description: "Simple CLI written for the sake of the example",
commands: [
cliparse.command(
"number",
{ description: "perform simple arithmetic calculations",
commands: [
cliparse.command(
"add",
{ description: "add two integers",
args: [ intArgument, intArgument]
}, numberModule.add),
cliparse.command(
"multiply",
{ description: "multiply two integers",
args: [ intArgument, intArgument]
}, numberModule.multiply)
]
}),
]
});
An help command is automatically generated, with the following syntax:
`bash`
$ my-executable help
It can be disabled by setting helpCommand to false in cliparse.cli options.
CLI parse allows you to generate autocompletion scripts for bash and zsh (work
in progress). Generate the script in your npm post-install hook and add it to
your users shell completion scripts to enable it.
It supports completion on commands, options and arguments, as well as on the
help command. Completion on options and arguments are configurable: you can
declare your own completion methods.
All the completion logic is handled within your app, so it will work with
dynamically defined commands.
Generate the completion script and put it in bash completion dir:
`bash`
$ my-executable --bash-autocomplete-script /complete/path/to/my-executable > ~/.bash_completion.d/my-executable
Normally .bash_completion.d is automatically sourced. You can put the file
where you want and source it manually.
Generate the completion script and put it in zsh completion dir:
`bash`
$ my-executable --zsh-autocomplete-script /complete/path/to/my-executable > ~/.zsh.d/completion/_my-executable
The file name must be _my-executable (if your executable is namedmy-executable). You can put the file where you want as long as it's in a$fpath
directory listed in .
You can have custom completion for option or arguments, by passing a custom
complete function (see API).
For instance to complete on a list of colors:
`javascript`
var colorCompleter = function() {
return autocomplete.words(['mauve', 'blue', 'yellow', 'purple', 'parabolic']);
};
To complete on a list of files:
`javascript`
var fileCompleter = function() {
return autocomplete.files;
};
The complete function can also return a promise for async results.
`javascript`
cli(opts, cb);
Where opts can contain
- name: the name of the executable (if not provided, process.argv is used)description
- : a one-line description of the executableversion
- : the version number of the executable (displayed by --version.null
Default value: options
- : array of top-level options (constructed with option or flag). Default[]
value: .commands
- : array of commands (constructed with command). Default value: []args
- : array of arguments (constructed with argument). If your apphelpCommand
doesn't have commands.
- : Generate a help command. Default value: true.
If your application is not solely made of commands, you can pass an action
callback. If you don't give a callback, calling your application without any
argument will display a usage message describing the available commands.
`javascript`
option(name, opts);
Where name is the name of the flag, and opts can contain
- aliases: array of other names (the shorthand name for instance. Default[]
value: metavar
- : the name of the value of the option (if applicable: for flags,parser
see below)
- : the parser used to parse the value. Default value: stringParserdescription
which is a noop parser returning the string.
- : a single-line description of what the option is about. Defaultrequired
value: the empty string.
- : make option mandatorydefault
- : value used if the option is not given any value. If set,required
overrides the setting.complete
- : a function returning completion results for the option (or aexpects_value
promise of results). Default value: a function returning an empty result.
- : does the option expect a value? Default: true. Rather thanflag
setting it yourself, use .
Shorthand for flags (ie options with boolean values, defaulting to false,
doesn't expect a value)
`javascript`
flag(name, opts);
Acts like option, with different defaults:
- parser defaults to booleanParser, which parses boolean valuesdefault
- defaults to false
`javascript`
argument(name, opts);
Where opts can contain
- parser: ther parser used to parse the value of the argument. DefaultstringParser
value: description
- : a single-line description of what the argument is about.default
- : value used if the argument is not given any valuecomplete
- : a function returning completion results for the argument. Default
value: a function returning an empty result.
`javascript`
command(name, opts, cb);
Where name is the name of the command , and opts can contain
- description: a single line description of the commandargs
- : array of arguments (constructed with argument). Default value: []options
- : array of options (constructed with option). Default value:[]
privateOptions
- : array of options that will not be inherited in sub commands. Default value:[]
commands
- : array of subcommands (constructed with command). Default[]
value:
cb is a callback which is called when the command match (if no subcommand{ args: ['value'], options: {key: 'value'}}
match). It is called with a object. opts contains
both the options of the command and the options of the parent commands.
Basic scalar types (int, bool, and string) are already supported. It is
possible to declare your own parsers to validate more specific types of values
(eg. enums).
A parser is a function String -> Result where Result is either
- { success: { error:
- or
Parser results can be constructed with parsers.success( andparsers.error(.
For instance, to parse an hexadecimal RBG color:
`javascript`
var colorParser = function(input) {
var pattern = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i;
var matches = input.match(pattern);
if(matches !== null) {
var components = matches.slice(1,4)
.map(function(x) { return parseInt(x, 16); });
return parsers.success(components);
} else {
return parsers.error("invalid color code");
}
}
#### Autocompletion results
autocomplete.empty: no results
autocomplete.words([…]): list of words
autocomplete.glob(: files matching glob (eg. *.log).
autocomplete.files: files
autocomplete.directories: directories
You can combine autocompletion results:
autocomplete.mappend(: combine results from result1 andresult2. As globs can't be combined, the last one wins (if set).
autocomplete.mconcat([ : reduce a list of result to a compositemappend
result with . If the list is empty, then empty is returned.
Make sure you don't break anything.
`bash``
npm test
- [x] Declare flags as boolean options in minimist
- [ ] Variadic arguments
- [ ] Parse failure on unrecognized options / arguments
- [ ] Cleaner display of errors
- [ ] [Dedicated ZSH completion (help welcome :-\])](https://github.com/divarvel/cliparse-node/issues/9)