Add support for recursive --help

[RicardoM17]

Description

Right now if we do:

cli --help

We get a list of the commands. And if we then do:

cli command --help

We get further info from this command.

It would be nice to have some command where one can generate everything in one go.

[DannyBen]

Hmm. This behavior is the standard in most complex CLIs.

Otherwise, there is the potential for a very long and convoluted help message, where each command has its own argument help, environment variable help etc - all in one long output.

Can you point to any notable command that does that, so I have a better reference of what you expect to see?

[RicardoM17]

For the record I'm not suggesting to change the current behavior of the cli help command. That is perfectly fine and suitable for 99% of the use cases.

However we just had a situation in our use case where it would have been nice to have all the information in one go, rather than have it nested, but it's nothing very specific.

So we decided to check if there was a cli -h -v or some other flag (no preference here) to recursively go through each command and add it to the output. Since there wasn't I decided to make a request here :D

I am not 100% sure what you are asking so apologies if I'm off the mark but the idea is that, from cli -h where we get:

...
Commands:
  start              Start docker services
  stop               Stop docker services
...

We could get:

...
Commands:
  start              Start docker services
  < output of cli start -h>
  stop               Stop docker services
  < output of cli stop -h>
...

Maybe with some care to not repeat info.

[DannyBen]

Alright.

1. There is most likely a way to implement it yourself, say, as a cli help command or something, and utilizing the *_usage() functions.
2. In addition, you can use the bashly render command to render this command automatically.
3. I will try to implement the above as an example, to see how it looks.
4. I am open to the idea of adding this as a feature, or at least as an example for "self service" implementation.

[DannyBen]

Try this for size.

In a new folder, create a new bashly project with colors library:

$ bashly init
$ bashly add colors

add help command to bashly.yml:

commands:
- name: help
  alias: h
  help: Show full (recursive) help

generate:

$ bashly generate

edit src/help_command.sh as follows:

cli_usage
echo

long_usage=1
bold "download command"
echo
cli_download_usage
echo

bold "upload command"
echo
cli_upload_usage
echo

generate and run:

bashly generate
./cli help

[RicardoM17]

cli - Sample application

Usage:
  cli COMMAND
  cli [COMMAND] --help | -h
  cli --version | -v

Commands:
  download   Download a file
  upload     Upload a file
  help       Show full (recursive) help


download command

cli download - Download a file

Alias: d

Usage:
  cli download SOURCE [TARGET] [OPTIONS]
  cli download --help | -h

Options:
  --force, -f
    Overwrite existing files

  --help, -h
    Show this help

Arguments:
  SOURCE
    URL to download from

  TARGET
    Target filename (default: same as source)

Environment Variables:
  DEFAULT_TARGET_LOCATION
    Set the default location to download to

Examples:
  cli download example.com
  cli download example.com ./output -f


upload command

cli upload - Upload a file

Alias: u

Usage:
  cli upload SOURCE [OPTIONS]
  cli upload --help | -h

Options:
  --user, -u USER (required)
    Username to use for logging in

  --password, -p PASSWORD
    Password to use for logging in

  --help, -h
    Show this help

Arguments:
  SOURCE
    File to upload

Looks pretty good.

[DannyBen]

Then you can do it for your app.

You can also render this file automatically, using the custom rendering feature. At this point, it is unlikely to become a built-in bashly feature, for reasons I mostly mentioned already plus the fact that different users of such a feature might want a slightly different format.