Your solution works, but has the drawback (like you mentioned) that the usage help message is static and won't reflect future updates like new subcommands or options being added.

Picocli does provide a way to customize the usage help message dynamically via its Help API. This allows you to reorder or replace sections in the usage help message. I believe the section you want to replace is the command list section.

This will require a bit of a deep dive into the picocli usage help model. To help you get started, the picocli-examples module has some custom help examples. This example shows how to modify the usage help message to show the full command hierarchy (without options though), which is fairly close to what you want to do. You could take it as a starting point. If you have more questions feel free to raise tickets on the picocli github issue tracker (or here).

Picocli offers the @Parameters annotation for positional parameters, in addition to the @Option annotation, which is for named parameters.

If you use the @Parameters annotation for the number, instead of @Option(names = "n"), then end users can invoke the command as open 1.

That is a fairly minimal change, the resulting code could look like this:

@CommandLine.Command(name = "open",
    mixinStandardHelpOptions = true,
    version = "1.0",
    description = "Open note")
@Getter
@ToString
public class OpenCommand implements Runnable {
    @CommandLine.ParentCommand TopLevelCommand parent;

    @CommandLine.Parameters(description = "Number of notes to open")
    private Integer number;

    public void run() {
        System.out.printf("Number of notes that will be opened: %s%n", number);
    }
}

The picocli user manual has two sections that may be relevant:

• Running the application
• Packaging your application

Running it (from the command line, not from the IDE) is important to ensure you know exactly what the classpath is, what the fully qualified main class is etc.

Packaging has to do with creating a distribution. This can be as simple as creating a unix alias, but more robust options are creating a launcher script, or compiling your application into a native executable with GraalVM. The article Build Great Native CLI apps in Java with GraalVM and picocli gives a lot of details and pitfalls on creating a native executable.