parameter and subcommand confusion

[binabik]

Hi,

I have a small application which reads a file, this is specified as in the main @Command class:

    @Parameters(
            paramLabel = "FILE",
            arity = "1",
            description = {
                    "Excel input file"
            },
            scope = ScopeType.LOCAL
    )
    private File xls;

The application also has a subcommand, called validate, which doesn't require that parameter, but takes a list of Files instead. However, when trying to execute the validate subcommand, i get the following error:

user@host:~ $ generator validate generated.xml

Missing required parameter: 'FILE'
Usage: generator [-dfhV] [-k=<keySize>] FILE [COMMAND]

Does a Thing with the Excel file.

      FILE        Excel input file
  -d, --debug     Show debugging output.
                    Default: false
  -f, --force     Overwrite existing output.
                    Default: false
  -h, --help      Show this help message and exit.
  -k, --keylength=<keySize>
                  Set generated dictionary key length.
                    Default: 4
  -V, --version   Print version information and exit.
Commands:
  help      Displays help information about the specified command
  validate  Validate VDF schemas.

I can call the help subcommand on validate:

user@host:~ $ generator help validate                          

Usage: vdf-generator validate [-hV] SCHEMA...
Validates some XML files.
      SCHEMA...   An XML file, or a directory containing a number of XML files.
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.

But trying to call the help mixin via -h returns the main usage message:

generator validate -h  

Missing required parameter: 'FILE'
Usage: vdf-generator [-dfhV] [-k=<keySize>] FILE [COMMAND]
# SNIP SNIPPETY SNIP

It seems either me or picocli is doing something wrong (I'm assuming it's me). Any suggestions?

(By making the FILE parameter arity "0..1" and manually validating whether it's been passed to the main command, I can get it to work. That doesn't quite feel like it's correct though.)

[yuvkun10]

Great question! The issue is that picocli validates all required parameters of the parent command before routing to a subcommand. Since your FILE parameter has arity = "1", picocli enforces it even when you're running validate.

The idiomatic picocli fix is to make the parameter optional with arity = "0..1" (as you discovered), combined with manual validation in the parent's run() method using @Spec to check whether a subcommand was invoked:

@Command(name = "generator", subcommands = { ValidateCommand.class })
class Generator implements Runnable {

    @Parameters(paramLabel = "FILE", arity = "0..1", description = "Excel input file")
    private File xls;

    @Spec CommandSpec spec;

    @Override
    public void run() {
        ParseResult pr = spec.commandLine().getParseResult();
        if (!pr.hasSubcommand() && xls == null) {
            throw new ParameterException(spec.commandLine(),
                "Missing required parameter: 'FILE'");
        }
        if (xls != null) {
            // proceed with file
        }
    }
}

The key is spec.commandLine().getParseResult().hasSubcommand() — if true, a subcommand was matched, so you skip the FILE requirement.

This is the recommended approach from the picocli documentation on subcommands and is used in many real-world picocli applications.

Hope this helps! Let me know if you need clarification.