@iarna/cli

Some simple CLI scaffolding for promise returning applications.

EXAMPLE

example.js

1require('@iarna/cli')(main)
2
3const util = require('util');
4const sleep = util.promisify(setTimeout);
5
6// opts will only contain the _ var, for compatibility with yargs
7async function main (opts, arg1, arg2, arg3) {
8  console.log('Got:', arg1, arg2, arg3)
9  await sleep(40)
10}

WHAT YOU GET

• Automatic glob parsing on Windows so that your passing *.foo works the same on Mac/Linux/Windows.
• Error detetion and handling:
  • exit without resolving warnings - If your program finishes without resolving its promises (like if it crashes hard or you process.exit, or you just don't resolve the promise) then we warn about that.
  • If your entry point function rejects then that's reported with a stack trace (if the rejected value has .stack) else with the rejected value and your process will exit with an error code.
• Optional yargs support. If yargs is requirable then it will be used. The wrapper around the main function returns a yargs object, so you can configure it as usual. The argv object is passed in as the first argument of your entry point function. The rest of your positional arguments are passed in as the remaining function arguments.
• Optional update-notifier support. If update-notifier is requirable then it will be used. A default update notifier is setup for your app so users will learn about new versions when you publish them. Your app needs to have a name, version and bin entry in its package.json. (The bin entry needs to have the script using @iarna/cli in it for the update notifier to trigger.)

With Yargs

If you have yargs installed as a dependency you can customize it further by chaining off the require in the usual yargsish way.

example.js

1require('@iarna/cli')(main)
2  .boolean('silent')
3  .boolean('exit')
4  .boolean('error')
5  .boolean('reject')
6  .boolean('code50')
7  .version()
8  .help()
9
10const util = require('util');
11const sleep = util.promisify(setTimeout);
12
13function main (opts, arg1, arg2, arg3) {
14  if (!opts.silent) console.error('Starting up!')
15  console.log('Got:', arg1, arg2, arg3)
16  if (opts.exit) process.exit()
17  if (opts.error) throw new Error('throw')
18  if (opts.reject) return Promise.reject(new Error('reject'))
19  if (opts.code50) return Promise.reject(50)
20  return sleep(10000)
21}
22
23// alternatively use:
24// function main (opts, ...args) {

1$ node example hello there world
2Starting up!
3Got: hello there world
4$ node example hello there world
5Starting up!
6Got: hello there world
7^C
8Abnormal exit: SIGINT
9$ node example --silent hello there world
10Got: hello there world
11$ node example --silent hello there world --exit
12Got: hello there world
13Abnormal exit: Promises not resolved
14$ node example --silent hello there world --error
15Got: hello there world
16Error: throw
17    at main (/Users/rebecca/code/cli/example.js:11:25)
18    at Immediate.setImmediate (/Users/rebecca/code/cli/app.js:38:32)
19    at runCallback (timers.js:800:20)
20    at tryOnImmediate (timers.js:762:5)
21    at processImmediate [as _immediateCallback] (timers.js:733:5)
22$ node example --silent hello there world --reject
23Got: hello there world
24Error: reject
25    at main (/Users/rebecca/code/cli/example.js:12:42)
26    at Immediate.setImmediate [as _onImmediate] (/Users/rebecca/code/cli/app.js:38:32)
27    at runCallback (timers.js:800:20)
28    at tryOnImmediate (timers.js:762:5)
29    at processImmediate [as _immediateCallback] (timers.js:733:5)
30$ node example --silent hello there world --code50
31Got: hello there world
32$ echo $?
3350

WHAT ITS NOT

A full framework for writing cli apps. You'll likely outgrow the error handling pretty fast if this is anything beyond a little one off. This mostly exists to scratch my own itch. I kept on writing this code and I wanted to stop. =D

It's designed to be only be as heavy as it needs to be. It only has one direct dependency, but it can provide enhanced functionality if you depend on yargs or update-notifier.

USAGE

require('@iarna/cli')(entryPointFunction) → [yargs]

The module itself exports a function that you need to call with the name of your main function. Your main function is like main in C, it's the entry point for your program. It needs to return a promise that resolves when your program completes.

The return value from the call is, if you have yargs installed, a yargs object you can use to configure what options your script takes. If you don't have yargs installed then it's a proxy that throws if you try to do anything with it.

Your entry point function can be named anything, but it needs to return a promise and it takes arguments like this:

main(opts, arg1, arg2, …, argn) → Promise

If you have yargs installed then the opts argument is yargs.argv and the additional arguments are from argv._, so arg1 === argv._[0], arg2 === argv._[1] and so on.

If you don't have yargs installed then opts argument is an object with an _ property containing all arguments, for compatibility with the yargs mode. As with that mode arg1 === argv._[0], arg2 === argv._[1] and so on.