roar
CLI utilities / helpers based on meow and minimist
Overview
- Parses arguments with either meow or minimist
- Uses
debug
to provide a small logger - Uses
chalk
andlog-symbols
to extend the logger - Generates help output
- Helpers for I/O (fs, spawn / exec, glob)
- Error handlers to report with error level
- Command line completion
- Two flavors: ES6 Class or the more functionnal approach
Roar uses either meow or minimist to parse command-line arguments and options, which needs to be installed alongside roar.
# to use minimist
npm install minimist mklabs/roar -S
# to use meow
npm install meow mklabs/roar -S
// To use minimistconst parser = ;const roar = parser; // To use meowconst parser = ;const roaw = parser; const cli = ;
roar.CLI
cli
is an instance of roar.CLI
. This class exposes various utilities for
parsing options and logging purpose.
const cli = ; // Similar toconst command = options;
Options
- namespace - Define the debug namespace (eg. require('debug')(namespace)).
- success - Success message to print with end()
- name - Command name (default: determined from process.argv)
- argv - Original array of arguments to parse with minimist (default: process.argv.slice(2))
- env - Environment variables (default: clone of
process.env
) - leftpad - Used to generate help output (default:
' '
) - padding - Used to generate help output (default:
20
) - stream - Log output streap (default: process.stderr)
On creation, the following properties will be created:
const cli = ; cliargv // minimist or meow result from "options.argv" or process.argv.slice(2)clialias // if defined, is used to parse arguments with minimistcliflags // if defined, is used to parse arguments with minimistcliexample // if defined, is used to generate help outputclimore // if defined, is used to generate help outputclidebug // debug module logger, enabled with -d flagclienv // options.env or a clone of process.envclistart // Timestamp marking instance creation, namely used to report // build time with `CLI.end()`
Some static methods:
- CLI.fail - to invoke with an error, log the error with npmlog error level
- CLI.end - Log options.success message with elapsed time as a parameter
Usage
While you can create a CLI instance and interact with it, you can extend
roar.CLI
and use your own CLI class. This is the recommended way as it allows
greater flexibility and is more suited to complex scenario.
const CLI = ; { return 'mycp <argument> [options]'; } { return ` Examples: $ mycp *.js foo/`; } // Used to parse arguments with minimist { return h: 'help' v: 'version' d: 'debug' f: 'force' ; } // Used to generate the help output, along with example / more above { return help: 'Show this help output' version: 'Show package version' debug: 'Enable extended log output' force: 'Force file write even if already existing' skip: 'Skip scripts hook' ; } let cmd = namespace: 'cmd'; // Enabled with `-d, --debug` flagcmd; // Output generated help and exit with 0if cmdargvhelp cmd; cmd; // Log helperslog;log;log;log;
Logger
The logger is based on debug, chalk and log-symbols.
All logs are written to STDERR, unless you provide a different stream.
If you'd like to redirect all logs to a file, you can provide an instance of fs.WriteStream
:
const fs = ;let output = let cli = ;
The DEBUG
environment variable is used to enable a specific set of
namespaces, which is used with this.debug()
, or turned on specifically for
roar instances with -d, --debug
flag.