Piral CLI extension arguments format

Question

I was looking into developing a piral-cli extension and had a couple questions about the CliPluginApi interface:

module.exports = function (cliApi) {
  cliApi.withCommand({
    name: 'dependencies-pilet',
    alias: ['deps-pilet'],
    description: 'Lists the dependencies of the current pilet.',
    arguments: [],
    flags(argv) {
      return argv
        .boolean('only-shared')
        .describe('only-shared', 'Only outputs the declared shared dependencies.')
        .default('only-shared', false)
        .string('base')
        .default('base', process.cwd())
        .describe('base', 'Sets the base directory. By default the current directory is used.');
    },
    run(args) {
      // your code here, where args.onlyShared refers to our custom argument
    },
  });
};

What is the distinction between arguments and flags in a ToolCommand? Are arguments just required positional arguments? Need the positionals be listed again?

Final question on this one - I want to get a list of positionals like an array. Whats the syntax for this? I tried arguments: ['list[]'], but it did not work.

Answer 1

Yes arguments are positional, however, they may be optional, too.

For anything in this area please check out the documentation of Yargs. This may be helpful.

Still you may use flags with the argv to describe these positionals, e.g.:

return argv
    .positional('source', {
        type: 'string',
        describe: 'Sets the source root directory or index.html file for collecting all the information.',
        default: apps.debugPiralDefaults.entry,
    })
    // ...

Regarding your question with the array: To allow multiple you can use the .. suffix for your positional name.

In your case that would have meant: arguments: ['[list..]'],.

In Yargs [] does not mean array, but rather optional. This is opposed to <>, which means required. For the positional description still use, e.g., string -> you only describe one element here, but since you specified .. the transported data type will always be an Array<T>, where T is the single type you gave to Yargs.

Hope that helps!