Inherited sometimes-required mixins and/or command line option ordering

[jrivard]

I'm building a CLI tool using the excellent picocli library. My tool has about a dozen subcommands, many of which share a complex set of options with validations and mutual exclusivity. I handle these shared options using a mixin across most subcommands, which works technically but leads to awkward UX for users.

My structure looks like this:

base-command
   sub1  +mixin1
   sub2  +mixin1
   sub3  +mixin1
   sub4  +mixin2
   sub5  

mixin1
  - required and optional options, arg groups, and validations

mixin2
  - required and optional arguments

The problem:
All option names are globally unique. Most mixin1 options are required and frequently used, but because they're defined on the subcommands, users must place them after the subcommand. This is unintuitive since users tend to provide these options first and only change the subcommand (and a few other options) using shell history.

A related issue is with @file support: it also must appear after the subcommand, which further complicates the user experience.

I understand why this behavior exists given picocli's design, but I'd like to make the option order more flexible for users.

What I've tried:

1. Inheritance: Not feasible because mixin1 has required options.
2. Moving mixin1 to base-command: This forces irrelevant options on subcommands that don't use mixin1 (e.g., sub3).
3. ArgGroup approaches: I reviewed the [ArgGroupMixinDemo2.java](https://github.com/remkop/picocli/blob/main/picocli-examples/src/main/java/picocli/examples/arggroup/ArgGroupMixinDemo2.java) example, but it doesn't seem to fit because of required options.

Potential workaround:

I could duplicate mixin1—one version required on subcommands and another optional on base-command—and manually sync the values. This feels cumbersome and error-prone.

My questions:

1. Is there a cleaner way to allow options from mixin1 to be accepted both before and after subcommands?
2. Is there a way to make @file work regardless of its position?

Any insights or alternative approaches would be greatly appreciated!

[remkop]

Hi @jrivard nice to hear you like the library!

First, about @file, what makes you say it doesn't work regardless of its position? Can you describe how you use it, what happens, and how you would like to use it?

Second, one idea (you may not like it) is to let go of having a single base-command. If you split them up into multiple top-level commands, the user experience may be much nicer...

[jrivard]

First, about @file, what makes you say it doesn't work regardless of its position? Can you describe how you use it, what happens, and how you would like to use it?

Sure. Using the example I placed above, Say 'mixin1' has required option --hostname, and I have a file with contents of --hostname=www.example.com.

If I use a cli of:

base-command @file sub2 -otherOption

The picocli parser will result in a missing parameter hostname error, because base-command does not have a --hostname option. A cli invocation of base-command sub2 @file -otherOption will work fine. While this makes total sense given the way my options are structured, this is not intuitive to the command line user. I believe the end user would be surprised to learn the @file is positionally dependent.

Second, one idea (you may not like it) is to let go of having a single base-command. If you split them up into multiple top-level commands, the user experience may be much nicer...

This idea is very appealing to me, because it totally resolves the logical inconsistency. However I think it would result in even worse UI for the end-user. My experience is that end users do not appreciate or enjoy having to understand hierarchy of any kind. I have learned this lesson the hard way repeatedly over the years and it's been repeated to me by UX experts. Probably the debatable point is whether a cli user qualifies as this type of end user or more like most of us developers that can't understand a logical machine without hierarchies. :) I would guess a substantial part of the users of my tool will be the former. It's this UX philosophy that pushes my desire for order-agnostic options across the command hierarchy.

[remkop]

Thanks for the clarification. Yes, @-files are simply expanded in place, they don't sort of "jump" subcommand boundaries or become globally applicable to all subcommands or anything like that.

The reality is that any command with subcommands is a hierarchy.
One extreme idea is to have no subcommands at all, and just have top-level commands.
A variation is some hybrid: break up the application into multiple top-level commands that are more cohesive, for example have a top-level command with the subset of subcommands where your mixin with shared mandatory options does make sense for all subcommands in this subset.

Another thought is to provide defaulting to alleviate the pain of mandatory options.
Picocli's built-in PropertiesDefaultProvider may be useful.
In the description of your options, you can use the ${DEFAULT-VALUE} variable so that the usage help of the command shows these default values.

I hope this is useful.