Cannot create CLI with specific with synopsis - CLI with Picocli

I would like to create a CLI in picocli with the following synopsis

Command (--option1=<value1> [--req11=<v11> --req12=<v12> --req13=<v13>] | --option2=<value2> [--req21=<v21> --req22=<v22>] | --option3=<value3> | --option4=<value4>) 

I tried to create nested groups but it didn't work out.

Using nested groups, I was able to create this synopsis:

Usage: mycmd ((--option1=<value1> [--req11=<v11> --req12=<v12> --req13=<v13>])
             | (--option2=<value2> [--req21=<v21> --req22=<v22>]) |
             (--option3=<value3>) | (--option4=<value4>))

This is functionally identical to your target synopsis but has some redundant braces.

Here is the code:

import picocli.CommandLine;
import picocli.CommandLine.ArgGroup;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;

@Command(name = "mycmd")
public class SynopsisDemo implements Runnable {

    static class Group1 {
        @Option(names = "--option1", required = true)
        String value1;

        @ArgGroup(exclusive = false, multiplicity = "0..1")
        Group1Inner inner1;
    }

    static class Group1Inner {
        @Option(names = "--req11", required = true) String v11;
        @Option(names = "--req12", required = true) String v12;
        @Option(names = "--req13", required = true) String v13;
    }

    static class Group2 {
        @Option(names = "--option2", required = true)
        String value2;

        @ArgGroup(exclusive = false, multiplicity = "0..1")
        Group2Inner inner2;
    }

    static class Group2Inner {
        @Option(names = "--req21", required = true) String v21;
        @Option(names = "--req22", required = true) String v22;
    }

    static class Group3 {
        @Option(names = "--option3", required = true)
        String value3;
    }

    static class Group4 {
        @Option(names = "--option4", required = true)
        String value4;
    }

    static class AllGroups {
        @ArgGroup(exclusive = false, multiplicity = "1") Group1 group1;
        @ArgGroup(exclusive = false, multiplicity = "1") Group2 group2;
        @ArgGroup(exclusive = false, multiplicity = "1") Group3 group3;
        @ArgGroup(exclusive = false, multiplicity = "1") Group4 group4;
    }

    @ArgGroup(exclusive = true, multiplicity = "1")
    AllGroups allGroups;

    @Override
    public void run() {
        // business logic here
    }

    // Goal:
    // Command (--option1=<value1> [--req11=<v11> --req12=<v12> --req13=<v13>]
    //         | --option2=<value2> [--req21=<v21> --req22=<v22>]
    //         | --option3=<value3> | --option4=<value4>)
    public static void main(String[] args) {
        //new CommandLine(new SynopsisDemo()).execute(args);
        new CommandLine(new SynopsisDemo()).usage(System.out);
    }
}

I tried getting rid of the braces around --option3 and --option4 by moving the @Option definitions out of Group3/4 and into AllGroups, but that resulted in these options moving to the beginning of the synopsis:

Usage: mycmd (--option3=<value3> | --option4=<value4> | (--option1=<value1>
             [--req11=<v11> --req12=<v12> --req13=<v13>]) | (--option2=<value2>
             [--req21=<v21> --req22=<v22>]))

I then tried to move those options to the end by specifying order, like this:

static class AllGroups {
    @ArgGroup(exclusive = false, multiplicity = "1") Group1 group1;
    @ArgGroup(exclusive = false, multiplicity = "1") Group2 group2;
    @Option(names = "--option3", required = true, order = 3) String value3;
    @Option(names = "--option4", required = true, order = 4) String value4;
}

But it looks like order can currently only be used to control where options and arg-groups appear in the options list, it does not affect the synopsis. I opened this issue in the picocli issue tracker for that. Your input on that ticket is very welcome.

Workaround

Meanwhile, you can get the exact synopsis you want by specifying a custom synopsis, like this:

@Command(name = "mycmd",
        customSynopsis = {
                "mycmd (--option1=<value1> [--req11=<v11> --req12=<v12> --req13=<v13>]",
                "       | --option2=<value2> [--req21=<v21> --req22=<v22>]",
                "       | --option3=<value3> | --option4=<value4>)"
        })
public class SynopsisDemo implements Runnable { // ...

This results in the following synopsis (which I believe matches your requirements):

Usage: mycmd (--option1=<value1> [--req11=<v11> --req12=<v12> --req13=<v13>]
       | --option2=<value2> [--req21=<v21> --req22=<v22>]
       | --option3=<value3> | --option4=<value4>)