What does it mean for a not-parent command to contain a commands field?

[jpluscplusm]

The Exec, KV, and RPC command types allow both a command key and a commands key. The commands key is described as "Additional CLI commands to add".

Is the intent for non-Parent commands being able to act as parents, whilst also being individually-addressable?

Speaking as someone less talented than your target audience: as a mediocre Ops, I would personally find it more understandable if only Parent commands were allowed to contain the commands key, and could define child-commands. This would stop me having to figure out if invoking Exec-command-X-containing-child-commands-Y-and-Z would actually invoke just X; or X then Y and Z; does invoking Z directly also have some element of dependency/pre-req handling - does X get invoked beforehand, because the nesting is intended to communicate some sort of "don't do Y without doing X first"?

I'm not saying everyone's as dumb as I am - just that I feel there's ambiguity of intent, there, which could be neatly removed if only Parent commands (and the root command) contained the commands key :-)

---- Edit:

A parallel thought/argument: if a Parent command's job, when invoked, were to display its own help text and that of its child commands, that'd be great DevX. That would let me run mycorp foo bar, and get told about all the foo bar {baz,quux,wibble} commands that I /could/ invoke. And it'd let me step up the hierarchy, from having run mycorp foo bar baz, by deleting "baz", re-invoking the command, and easily seeing what other commands were available at this level of the hierarchy.

But if there's a possibility that, by stepping up the hierarchy, I was maybe about to invoke an Exec command that was also acting as a parent, then this tactic of discovery isn't available to me. In that world, I can't risk invoking mycorp foo bar as a discovery mechanism, after invoking mycorp foo bar baz, in case foo bar actually does something significant.

[ripienaar]

$ nats stream cluster --help
usage: nats stream cluster <command> [<args> ...]

Manages a clustered Stream

Subcommands:
  stream cluster step-down [<stream>]
    Force a new leader election by standing down the current leader

  stream cluster peer-remove [<stream>] [<peer>]
    Removes a peer from the Stream cluster

here nats, stream and cluster are parents that does nothing, however nats stream cluster could print some kind of cluster info.

So a pure parent has no logic associated while a sub command that has logic can have optional further sub commands and logic of its own.

So I want to insist that a exec has all the needed things to make a functional exec...and parent has none of those I thought its clearer and I can do better validation that way

[ripienaar]

Yeah so to respond to your points in the edit, I tend to do as above where its parent->parent->exec, I try to avoid parent->exec->exec for those reasons. But someone might and the cli framework this is built on suppots that so might as well.

If you are going to have parent->exec->exec then I tend to make the middle exec a readonly/info action, something like:

$ kv <bucket> # shows info about bucket
$ kv <bucket> get <key> # gets a key

here we have an exec in the path to another exec and its fine (side effect free)