[wodenokoto]

I think autocomplete and sub commands can help a lot with discoverability.

I don't want to praise the Google Cloud CLI, but one nice thing is you can do something along the lines of

    $ gcloud <tab>
    -> list of services you want to manipulate
    $ gcloud servicename <tab>
    -> list of action you can do to service
    $ gcloud servicename actionname --help
    --> detailed information on how to apply that action

It isn't perfect - you don't get this behaviour out-of-the-box with every shell - but it is a lot better than reading a man page with a list of a million flags.