Feature request: add additional help description for subcommands

[willgcho]

Environment

• ascli 4.0.0.pre2
• Debian 9.13 x64, ruby 3.0.0p0
• Win10 x64, ruby 2.7.2p137

Description

I was hoping appending -h after a subcommand would give helpful information about that specific subcommand. For example, I wanted to learn how to specify the arguments to node subcommands like browse and download, and tried running something like ascli node download -h.

Unfortunately for me I'm asked to add the missing mandatory option --url and to "Use '-h' option to get help":

C:\Users\WDAGUtilityAccount\Downloads>ascli node download -h
ERROR: Argument: Missing mandatory option: url
Use '-h' option to get help.
ERROR: Argument: unprocessed values: ["download"]

C:\Users\WDAGUtilityAccount\Downloads>

After including the required arguments (url/username/password), it now shows a help message, but it's

1. needlessly long (perhaps cut out the first half and only include the relevant section under "COMMAND: node"), and
2. It still only lists what I would've seen by running "ascli -h" and does not further clarify how to use the download subcommand:

aspera@wcho-debian:~/Desktop$ ascli node --url=https://10.0.213.232:9092 --username=*** --password=*** download --help
NAME
        ascli -- a command line tool for Aspera Applications (v4.0.0.pre2)

SYNOPSIS
        ascli COMMANDS [OPTIONS] [ARGS]

DESCRIPTION
        Use Aspera application to perform operations on command line.
        Documentation and examples: https://rubygems.org/gems/aspera-cli
        execute: ascli conf doc
        or visit: http://www.rubydoc.info/gems/aspera-cli

COMMANDS
        To list first level commands, execute: ascli
        Note that commands can be written shortened (provided it is unique).

OPTIONS
        Options begin with a '-' (minus), and value is provided on command line.
        Special values are supported beginning with special prefix, like: @base64: @json: @zlib: @ruby: @csvt: @lines: @list: @val: @file: @path: @env: @stdin:.
        Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'

ARGS
        Some commands require mandatory arguments, e.g. a path.

OPTIONS: global
        --interactive=ENUM           use interactive input of missing params: yes, no
        --ask-options=ENUM           ask even optional options: yes, no
        --format=ENUM                output format: table, ruby, json, jsonpp, yaml, csv, nagios
        --display=ENUM               output only some information: info, data, error
        --fields=VALUE               comma separated list of fields, or ALL, or DEF
        --select=VALUE               select only some items in lists, extended value: hash (column, value)
        --table-style=VALUE          table display style
        --flat-hash=ENUM             display hash values as additional keys: yes, no
    -h, --help                       Show this message.
        --bash-comp                  generate bash completion for command
        --show-config                Display parameters used for the provided action.
    -r, --rest-debug                 more debug for HTTP calls
    -v, --version                    display version
    -w, --warnings                   check for language warnings
        --ui=ENUM                    method to start browser: text, graphical
        --log-level=ENUM             Log level: info, unknown, fatal, warn, debug, error
        --logger=ENUM                log method: stderr, stdout, syslog
        --lock-port=VALUE            prevent dual execution of a command, e.g. in cron
        --query=VALUE                additional filter for API calls (extended value) (some commands)
        --insecure=ENUM              do not validate HTTPS certificate: yes, no
        --once-only=ENUM             process only new items (some commands): yes, no

COMMAND: config
SUBCOMMANDS: gem_path genkey plugins flush_tokens list overview open echo id documentation wizard export_to_cli detect coffee ascp email_test smtp_settings proxy_check folder file
OPTIONS:
        --value=VALUE                extended value for create, update, list filter
        --property=VALUE             name of property to set
        --id=VALUE                   resource identifier (modify,delete,show)
        --config-file=VALUE          read parameters from file in YAML format, current=/root/.aspera/ascli/config.yaml
        --override=ENUM              override existing value: yes, no
    -N, --no-default                 do not load default configuration for plugin
        --use-generic-client=ENUM    wizard: AoC: use global or org specific jwt client id: yes, no
        --pkeypath=VALUE             path to private key for JWT (wizard)
        --ascp-path=VALUE            path to ascp
        --use-product=VALUE          use ascp from specified product
        --smtp=VALUE                 smtp configuration (extended value: hash)
        --fpac=VALUE                 proxy auto configuration URL
    -P, --presetVALUE                load the named option preset from current config file
        --default=VALUE              set as default configuration for specified plugin
        --secret=VALUE               access key secret for node
        --secrets=VALUE              access key secret for node
        --test-mode=ENUM             skip user validation in wizard mode: yes, no
        --ts=VALUE                   override transfer spec values (Hash, use @json: prefix), current={}
        --local-resume=VALUE         set resume policy (Hash, use @json: prefix), current=
        --to-folder=VALUE            destination folder for downloaded files
        --sources=VALUE              list of source files (see doc)
        --transfer-info=VALUE        additional information for transfer client
        --src-type=ENUM              type of file list: list, pair
        --transfer=ENUM              type of transfer: direct, httpgw, connect, node, aoc
        --progress=ENUM              type of progress bar: none, native, multi

COMMAND: node
SUBCOMMANDS: postprocess stream transfer cleanup forward access_key watch_folder service async central asperabrowser basic_token browse upload download api_details nagios_check events space info license mkdir mklink mkfile rename delete search
OPTIONS:
        --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
        --username=VALUE             username to log in
        --password=VALUE             user's password
        --validator=VALUE            identifier of validator (optional for central)
        --asperabrowserurl=VALUE     URL for simple aspera web ui
        --name=VALUE                 sync name
        --token=ENUM                 todo: type of token used for transfers: aspera, basic, auto
aspera@wcho-debian:~/Desktop$

And running the download subcommand without -h tells me that an argument is missing, but the help message doesn't show me how to properly format the source file list argument:

aspera@wcho-debian:~/Desktop$ ascli node --url=https://10.0.213.232:9092 --username=*** --password=*** download
ERROR: Argument: missing argument (multiple): source file list
Use '-h' option to get help.
aspera@wcho-debian:~/Desktop$

[laurent-martin]

The current implementation is that:
1- if no "command" is provided, "--help" will list all level1 commands with their options and level2 commands
2- if at least one command is provided: "--help" will list all options for this command and global and level2 commands for it.
More information is provided in the manual.
A quick fix it to display a line at the end of output of "--help" to tell go to the manual.
A better resolution would be to either:

• use a higher level CLI parser, such as thor or rbcli or other
• improve the current Cli::Manager
  Also, transfer spec options could be listed with: ascli conf ascp tsinfo
  (and mention this to the --ts option help)