help should match the normal CLI standards

[kcboyle]

an example help for commands from a library using jhanda:

ॐ  configure-director
This authenticated command configures the director.

Usage: om [options] configure-director [<args>]
  --client-id, -c, OM_CLIENT_ID                          string  Client ID for the Ops Manager VM (not required for unauthenticated commands)
  --client-secret, -s, OM_CLIENT_SECRET                  string  Client Secret for the Ops Manager VM (not required for unauthenticated commands)
  --connect-timeout, -o, OM_CONNECT_TIMEOUT              int     timeout in seconds to make TCP connections (default: 10)
  --decryption-passphrase, -d, OM_DECRYPTION_PASSPHRASE  string  Passphrase to decrypt the installation if the Ops Manager VM has been rebooted (optional for most commands)
  --env, -e                                              string  env file with login credentials
  --help, -h                                             bool    prints this usage information (default: false)
  --password, -p, OM_PASSWORD                            string  admin password for the Ops Manager VM (not required for unauthenticated commands)
  --request-timeout, -r, OM_REQUEST_TIMEOUT              int     timeout in seconds for HTTP requests to Ops Manager (default: 1800)
  --skip-ssl-validation, -k, OM_SKIP_SSL_VALIDATION      bool    skip ssl certificate validation during http requests (default: false)
  --target, -t, OM_TARGET                                string  location of the Ops Manager VM
  --trace, -tr, OM_TRACE                                 bool    prints HTTP requests and response payloads
  --username, -u, OM_USERNAME                            string  admin username for the Ops Manager VM (not required for unauthenticated commands)
  --version, -v                                          bool    prints the om release version (default: false)
  OM_VARS_ENV                                            string  **EXPERIMENTAL** load vars from environment variables by specifying a prefix (e.g.: 'MY' to load MY_var=value)

Command Arguments:
  --config, -c                string (required)  path to yml file containing all config fields (see docs/configure-director/README.md for format)
  --ignore-verifier-warnings  bool               option to ignore verifier warnings. NOT RECOMMENDED UNLESS DISABLED IN OPS MANAGER
  --ops-file                  string (variadic)  YAML operations file
  --var, -v                   string (variadic)  Load variable from the command line. Format: VAR=VAL
  --vars-env                  string (variadic)  Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
  --vars-file                 string (variadic)  Load variables from a YAML file

the help should look more like

This authenticated command configures the director.

Usage:
  om [options] configure-director [<args>]
 
Examples:
om --env env.yml configure-director --config config.yml

Flags:
  --config, -c                string (required)  path to yml file containing all config fields (see docs/configure-director/README.md for format)
  --ignore-verifier-warnings  bool               option to ignore verifier warnings. NOT RECOMMENDED UNLESS DISABLED IN OPS MANAGER
  --ops-file                  string (variadic)  YAML operations file
  --var, -v                   string (variadic)  Load variable from the command line. Format: VAR=VAL
  --vars-env                  string (variadic)  Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
  --vars-file                 string (variadic)  Load variables from a YAML file

Global Flags:
  --client-id, -c, OM_CLIENT_ID                          string  Client ID for the Ops Manager VM (not required for unauthenticated commands)
  --client-secret, -s, OM_CLIENT_SECRET                  string  Client Secret for the Ops Manager VM (not required for unauthenticated commands)
  --connect-timeout, -o, OM_CONNECT_TIMEOUT              int     timeout in seconds to make TCP connections (default: 10)
  --decryption-passphrase, -d, OM_DECRYPTION_PASSPHRASE  string  Passphrase to decrypt the installation if the Ops Manager VM has been rebooted (optional for most commands)
  --env, -e                                              string  env file with login credentials
  --help, -h                                             bool    prints this usage information (default: false)
  --password, -p, OM_PASSWORD                            string  admin password for the Ops Manager VM (not required for unauthenticated commands)
  --request-timeout, -r, OM_REQUEST_TIMEOUT              int     timeout in seconds for HTTP requests to Ops Manager (default: 1800)
  --skip-ssl-validation, -k, OM_SKIP_SSL_VALIDATION      bool    skip ssl certificate validation during http requests (default: false)
  --target, -t, OM_TARGET                                string  location of the Ops Manager VM
  --trace, -tr, OM_TRACE                                 bool    prints HTTP requests and response payloads
  --username, -u, OM_USERNAME                            string  admin username for the Ops Manager VM (not required for unauthenticated commands)
  --version, -v                                          bool    prints the om release version (default: false)
  OM_VARS_ENV                                            string  **EXPERIMENTAL** load vars from environment variables by specifying a prefix (e.g.: 'MY' to load MY_var=value)

This allows the library to behave more like other clis used by the general populous.

this will not be a breaking change, as it is only displaying the help differently. It also calls out which flags are specific to the command, and which ones are for every command in om, which was there, but not explicitly defined before. Command flags should take higher priority in the top-down help than global flags.

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this. Unfortunately, the Pivotal Tracker project is private so you may be unable to view the contents of the story.

The labels on this github issue will be updated when the story is started.

[matt-royal]

We would welcome a pull request to make this change, but are not likely to get to it ourselves any time soon.