You probably already know, but just in case you don't, you might read about http://docopt.org/ It seems to me a lot of your usage ideas could be refinements of / tooling around docopt-style interfaces.
Yeah I investigated. I don’t think it works well that direction. It is appealing and you can see some elements of it in my current design, though that’s a particular part I’m still unsure of.
It gets way too complicated real quick and a lot of things you _dont_ want to expose in documentation. It’s better to generate docs from a spec than the other way around, I’m pretty sure of this now.
There is also generating the whole thing from a function signature (e.g. https://github.com/c-blake/cligen ) since then CLauthors need not learn a new spec language, but then CLauthors must add back in helpful usage metadata/semantics and still need to learn a library API (but I like how those latter two things can be "gradual"). It's a hard space in which to find perfection, but I wish you luck in your attempt!
My goal is that one day framework authors will adopt this (they might do it quickly since it’s a hell of a lot easier to dump a usage spec and generate completions than it is figuring out how to write completions for each shell).
At that point it would make sense for them to also make scaffolding generators, meaning the cli author only has to write one spec and don’t have to repeat the effort for their code so much.
I think there are 2 ways usage will be used, either as an under the hood format used by frameworks to make frameworks better, or directly by users to scaffold framework code
It gets way too complicated real quick and a lot of things you _dont_ want to expose in documentation. It’s better to generate docs from a spec than the other way around, I’m pretty sure of this now.