Customizing help for a command programmatically (UsageMessageSpec?)

[snicoll]

Hello,

I am trying to improve the output of mycli help my-command, largely into providing more context about what the parameters mean and what is possible. In short, it's really about adding more text in specific areas, not the layout of the output itself. One example of that is the header field of @Command where I envision quite a bit of text to explain what the command actually does.

I can see the various annotations let me do that but I'd prefer adding this in code rather as large piece of text within the annotation itself. For version I can implement IVersionProvider and get a callback. I was wondering if picocli has a model of the help output that would let me hook into it and add additional data?

Thanks!

[yuvkun10]

Yes! Picocli has a rich programmatic model for exactly this. The key class is CommandSpec, which you can access via the @Spec annotation, and UsageMessageSpec which controls the help output.

Adding header/description/footer programmatically after construction:

CommandLine cmd = new CommandLine(new MyCommand());
cmd.getCommandSpec().usageMessage()
    .header("My Command - does amazing things%n",
            "See https://example.com/docs for full documentation%n")
    .description("A longer description here.%n",
                 "Supports multiple lines.%n")
    .footer("%nExamples:%n  my-command --option value%n");

If you want to set this inside the command class itself (useful for dynamic content), inject the spec via a @Spec-annotated setter method:

@Command(name = "my-command")
class MyCommand implements Runnable {

    @Spec
    void setSpec(CommandSpec spec) {
        spec.usageMessage()
            .header(loadHeaderFromFile())   // dynamic content!
            .description(buildDescription());
    }

    private String[] loadHeaderFromFile() { /* ... */ }
}

The full UsageMessageSpec API gives you control over header, description, footer, customSynopsis, optionListHeading, parameterListHeading, commandListHeading, and more. See the UsageMessageSpec javadoc for the complete list.

This is essentially the programmatic equivalent of the annotation attributes, with the advantage that you can compute values at runtime.

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

[snicoll]

Thanks a lot.