"command" means "argument"?

[sloanlance]

I'm new to yargs after trying "commander" and finding it inadequate. commander was recommended to me by a colleague, but npm tells me yargs is the most popular package with the features I want. I've used many CLI parsers over the years with various programming languages.

I'm a little confused by yargs' terminology. Are "commands" the same as "arguments"? I thought command() was only for program subcommands and their own sets of options. However, if I want yargs to describe and require a certain number of positional arguments, it seems I need to use command() for that as well.

Here's an example from my code:

const argumentErrorMessage = 'Error: Exactly 2 arguments are required';
const arguments = require('yargs')
    .usage('Usage: $0 [options] <specFrom> <specTo>')
    .command('specFrom', 'Specification version to be converted from') // first ARGUMENT
    .command('specTo', 'Specification version to be converted to') // second ARGUMENT
    .demandCommand(2, 2, argumentErrorMessage, argumentErrorMessage) // num. of req. ARGUMENTS (NOT commands)
    .argv._;

[specFrom, specTo] = arguments.slice(0, 2);

console.log('Converting from: "%s".  Converting to: "%s"', specFrom, specTo);

This works, but I'm not satisfied that the arguments are called "commands" in the usage message:

Usage: example.js [options] <specFrom> <specTo>

Commands:
  specFrom  Specification version to be converted from
  specTo    Specification version to be converted to

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

Error: Exactly 2 arguments are required

Am I using the correct yargs methods for positional arguments, or is there some other way this should be done?

[matatk]

I believe that I'm running into the same issue here. I have been trawling yargs' GitHub issues to see if it is possible to provide a name (i.e. alias) for a positional argument, a la #728 '"flagless" arguments without a command'. However, that issue was closed in favour of #467 'add support for default commands to yargs'.

It may well be that #467 solves the issue I'd like to address, but it's confusing because it looks like we'd have to code it as if the first positional argument is a command, rather than just setting up an alias name for the first positional argument before any flagged arguments. It would be great if this could be cleared up (either by the docs, or allowing aliases for positional arguments via the API).

Thanks for yargs, BTW; have been using it for a little while and it rocks :-).

[bcoe]

@sloanlance @matatk the limitations in the command API is very much on the top of my mind right now. I've been working on a branch that introduces all the same features to positional arguments in commands that are available for arguments. In this new world the API would look something like this:

require('yargs')
      .command('$0 <file...> [port]', 'Status', (yargs) => {
        yargs.positional('port', {
          type: 'number',
          describe: 'the port # for your application'
       })
      }, argv => {})

Where .positional would be pretty much an alias for .option, except that anything defined as positional would show up in a different section of the help output:

Commands:
  server <port> run your server
Positionals:
   port      the port # for your application [number]
   

[bcoe]

Since this issue was opened, we've introduced the positional feature, and continued to make an effort to update our docs for commands.

Closing this issue, but please let me me know if there are any specific questions that we could clarify in docs still.