yargs 5.0.0 Released

yargs 5.0.0 is currently published to the next tag. To try it out simply type the following:

npm cache clear; npm i yargs@next --save

This release is an exciting one: we’ve both introduced several slick new features (command suggestions, option coercion); and taken the opportunity presented by a major release to cleanup inconsistencies with yargs’ underlying API.

New Features

Recommended Commands

I love how git’s command-line-interface provides helpful suggestions when you accidentally type the wrong command:

  git: 'comit' is not a git command. See 'git --help'.

Did you mean this?
	commit

With the new recommendCommands() method, you can add this same functionality to your yargs applications:

  require('yargs')
  .command('hello', 'hello command')
  .command('goodbye', 'goodbye command')
  .recommendCommands()
  .argv

  $ ./cli.js helo

Commands:
  hello    hello command
  goodbye  goodbye command

Did you mean hello?

Option Coercion

yargs allows you to provide a type parameter for your options, hinting how the value should be interpreted, e.g., array, boolean, string.

This works great for simple values, but folks routinely ask for more complex parsing options; as an example, people have asked for the ability to parse JSON:

$ ./cli.js -j '{"message": "hello world!"}'

yargs’ new coercion feature allows you to apply an arbitrary parsing function to your options:

var argv = require('./')
  .option('j', {
    alias: 'json',
    coerce: function (arg) {
      return JSON.parse(arg)
    }
  })
  .argv

console.log(argv.json.message)

$ ./cli.js '{"message": "hello world!"}'

hello world!

I love the concept of coercion, it gives our users much more flexibility when parsing their arguments; without adding any significant complexity to yargs itself.

Breaking Changes

yargs 5.0.0 introduces several breaking changes, read carefully!

Fixes to Command API

yargs’ command API is a great way to build a complex nested command line application; in a nutshell, it allows you to decompose your command line application into individual commands, helping with the separation of concerns:

require('yargs')
  .command('foo', 'foo command', function (yargs) {
    // builder function, receives a yargs instance
    // which you can use to add command-specific options.
  }, function (argv) {
    // handler function, called once parsing is complete.
    console.log('foo')
  })
  .command('bar', 'bar command', {}, function (argv) {
    console.log('bar')
  })
  .argv

slick!

Commands are one of yargs’ most complex features, and we continue to iterate on their API; we’ve made the following command-related breaking changes in this release:

• default help command added: you can now simply type ./cli.js help, to receive yargs’ help output.
• changes to demand(): demand() now properly handles being invoked relative to a command; before this fix, the command itself would cause constraints to be applied incorrectly.
• builder no longer requires yargs to be returned: The third argument to command is a builder for describing options specific to the command. The builder command no longer requires that you return a yargs instance. Simply interact with the yargs instance passed as the first argument, and your options will take effect.
• builder now defaults to noop builder: the builder now resets all yargs configuration settings that are not flagged as being global.
• global fail: the fail() method now applies globally. This means that you can define a fail() handler once on the top-level yargs object, and nested failures in commands will bubble up to it.

Tweaks to Parser

yargs-parser is the underlying engine that processes the strings passed into process.argv.

We’ve made a couple breaking changes to the parser in this release:

• we now handle negative numbers: prior to this release negative numbers were interpreted as numeric options, with this release you can now pass negative numbers as values to options: -number -123.
• fixes to option groups: a bug has been fixed with option groups (-abc) terminated by numeric values (-abc123).

Miscellaneous

• fixed name of Chinese locale: we’ve renamed zh.json to zh_CN.json

What’s Next

The biggest thing currently on the core team’s mind is documentation. The yargs README has grown unwieldy! we have some plans in the works to help solve this problem:

• over the next few months expect to see targeted tutorials popping up on the yargs website; the first of which will likely be on the topic of commands.
• we’ve also created a gitter.im chatroom where folks can get help using yargs from its core contributors.

Hope you enjoy all the exciting updates in yargs 5.0.0!

– Ben.