Better CLI command usage prompt

[tjyang]

I was confused.

• Looks to me OPTIONS and COMMAND in Usage line should swap position ?

$ myapp-cli
The one-person framework for Rust

Usage: myapp-cli [OPTIONS] <COMMAND>

Commands:
  start     Start an app
  db        Perform DB operations
  routes    Describe all application endpoints
  task      Run a custom task
  generate  code generation creates a set of files and code templates based on a predefined set of rules
  doctor    Validate and diagnose configurations
  version   Display the app version
  help      Print this message or the help of the given subcommand(s)

Options:
  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
  -h, --help                       Print help
  -V, --version                    Print version
$

• start has more options about starting up both server and workers.

$ myapp-cli start -h
Start an app

Usage: myapp-cli start [OPTIONS]

Options:
  -w, --worker                     start worker
  -s, --server-and-worker          start same-process server and worker
  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
  -h, --help                       Print help
  -V, --version                    Print version
$

[ace3]

if we are to follow similar pattern as RoR, i think, yeah, we need to adjust it.

from RoR docs:

Usage:
  bin/rails COMMAND [options]

[jondot]

In this specific case the CLI framework is saying, these are the options:

  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
  -h, --help                       Print help
  -V, --version                    Print version

This is different from the command options.
I think that general things such as help, version, etc. are correct to appear before the subcommand itself.

[tjyang]

I would be less confused if Usage line is like following.
Adding -h to sinfiy one can ask more help information on sub-commands by adding one of options after.
[xx] = optional argument. | = or

Usage: myapp-cli [OPTIONS]  [COMMAND]  [OPTIONS]

[kaplanelad]

@tjyang, do we have something to do with that? or is this how clap works?

[tjyang]

@kaplanelad . I will submit PR if I found there is method to alter default Usage line output. Closing this discussion for now.

[tjyang]

@kaplanelad and @jondot

I spent some time to learn more about clap-4.x and found the USAGE line is adjustable by using help_template

Please review and let me know your comment.

• top level command usage is adjusted the display I like

[me@rocky9t01a saas_pg]$ saas_pg-cli
loco-rs 0.2.2 Dotan Nahum <[email protected]>, Elad Kaplan <[email protected]>
The one-person framework for Rust
Usage: [Options] [Commands] [Options]
Commands:
  start     Start an app
  db        Perform DB operations
  routes    Describe all application endpoints
  task      Run a custom task
  generate  code generation creates a set of files and code templates based on a predefined set of rules
  doctor    Validate and diagnose configurations
  version   Display the app version
  help      Print this message or the help of the given subcommand(s)

Options:
  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
  -h, --help                       Print help
  -V, --version                    Print version
[me@rocky9t01a saas_pg]$

• subcommand usage is not changed yet. OPTIONS should be changed as Options.

[me@rocky9t01a saas_pg]$ saas_pg-cli start -h
Start an app

Usage: saas_pg-cli start [OPTIONS]

Options:
  -w, --worker                     start worker
  -s, --server-and-worker          start same-process server and worker
  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
  -h, --help                       Print help
  -V, --version                    Print version
[me@rocky9t01a saas_pg]$

[kaplanelad]

@tjyang can you please add what we have and what are you expected to be?

[tjyang]

@kaplanelad

• Currently:
  loco app(sass_pg) using loco-rs:cli in loco/src/cli.rs generate rust code limited to following format.

$ saas_pg-cli
The one-person framework for Rust

Usage: myapp-cli [OPTIONS] <COMMAND>

Commands:
  start     Start an app
<snipped>
  help      Print this message or the help of the given subcommand(s)

Options:
  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
  -h, --help                       Print help
  -V, --version                    Print version
$

• Expacted:
  Adopting help_format in loco/src/cli.rs and other places, help format is like following when from using loco new to generate rust template code.

$saas_pg-cli
loco-rs 0.2.2 Dotan Nahum <[email protected]>, Elad Kaplan <[email protected]>   <-- Allow appname-version author format
The one-person framework for Rust                                                         <--  Allow desc
Usage: [Options] [Commands] [Options]                                                  <-- this is more syntax correct prompt format.
Commands:
  start     Start an app
 <snipped>
  help      Print this message or the help of the given subcommand(s)

Options:
  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
  -h, --help                       Print help
  -V, --version                    Print version
$

• End

[kaplanelad]

@tjyang got you.
Would you like to open a pull request?

[tjyang]

@kaplanelad , Thanks for the PR offer. I hope you can complete this RFE.
I know what I don't know(about loco-rs' code generation framework - rrgen ?).
This is not as easy( need to inject .help_format into loco-rs rust code generation framework) for loco-rs beginner like me.

[kaplanelad]

I'm currently dedicated to enhancing and incorporating more valuable features into Loco.
I think it better to defer for now this suggestion to later