ukaz

Next-generation command line parser for Node.js

Name

Pronounced /ǔːkaːz/ (oo-KAHZ)

Means "command" in Slovenian, or "decree" in Russian.

Get started

$ npm i ukaz

Usage

API is currently under development and is therefore unstable. Changes may be made at any time.

import * as ukaz from 'ukaz'

const app = new ukaz.Application('Hello world CLI app')
  .helpFlag() // adds -h, --help
  .validate() // ensures all required arguments are given before running handler
  .arguments('[phrases...]')
  .flag('-s|--shout', 'Shouts hello instead of being polite')
  .option('-n, --name <name>', 'A name to say hello to instead of "world"', {
    default: 'world'
  })
  .handler(async ({ flags, options, args }) => { // executed when the app runs
    let name = options.name.value
    if (flags.shout) {
      console.log(`HELLO, ${name.toUpperCase()}!!!`)
    } else {
      console.log(`Hello, ${name}!`)
    }

    if (args.phrases.present) {
      args.phrases.value.forEach(phrase => console.log(phrase))
    }
  })

app.run(process.argv)
  .catch(error => { // catches any errors encountered during execution
    if (error instanceof ukaz.CliParsingError) { // bad arguments or user input
      console.error(`Error: ${error.message}`)
    } else { // other application error
      console.error(error)
    }
  })

Another CLI app framework? But we already have [other framework]!

There are some great toolkits out there already, such as commander.js and nash. But most CLI frameworks for Node.js are not currently taking advantage of Node's support for async/await which can make your CLI app more robust.

ukaz intends to correct that:

• All handlers are async functions.
• Use async support to easily write synchronous or asynchronous code without unnecessary boilerplate.
• All errors are safely bubbled up to your error-handling code when you call app.run(...). Handle errors your way!
• You terminate the process on your own terms. No surprise process.exit(...) calls.
• Chain handlers together, much like middleware. Useful for larger, more involved applications.

Licence

MIT