Hide the global flag of etcdctl

[hwdef]

What would you like to be added?

Currently the output of etcdctl --help is as follows

./bin/etcdctl --help       
A simple command line client for etcd3.

Usage:
  etcdctl [command]

Key-value commands
  compaction  Compacts the event history in etcd
  del         Removes the specified key or range of keys [key, range_end)
  get         Gets the key or a range of keys
  lease       Lease related commands. Use `etcdctl lease --help` to see subcommands
  put         Puts the given key into the store
  txn         Txn processes all the requests in one transaction
  watch       Watches events stream on keys or prefixes

Cluster maintenance commands
  alarm       Alarm related commands. Use `etcdctl alarm --help` to see subcommands
  defrag      Defragments the storage of the etcd members with given endpoints
  downgrade   Downgrade related commands. Use `etcdctl downgrade --help` to see subcommands
  endpoint    Endpoint related commands. Use `etcdctl endpoint --help` to see subcommands
  member      Membership related commands. Use `etcdctl member --help` to see subcommands
  move-leader Transfers leadership to another etcd cluster member.
  snapshot    Manages etcd node snapshots

Concurrency commands
  elect       Observes and participates in leader election
  lock        Acquires a named lock

Authentication commands
  auth        Enable or disable authentication. Use `etcdctl auth --help` to see subcommands
  role        Role related commands. Use `etcdctl role --help` to see subcommands
  user        User related commands. Use `etcdctl user --help` to see subcommands

Utility commands
  check       commands for checking properties of the etcd cluster. Use `etcdctl check --help` to see subcommands
  completion  Generate completion script
  help        Help about any command
  make-mirror Makes a mirror at the destination etcd cluster
  version     Prints the version of etcdctl

Flags:
      --auth-jwt-token string        JWT token used for authentication (if this option is used, --user and --password should not be set)
      --cacert string                verify certificates of TLS-enabled secure servers using this CA bundle
      --cert string                  identify secure client using this TLS certificate file
      --command-timeout duration     timeout for short running command (excluding dial timeout) (default 5s)
      --debug                        enable client-side debug logging
      --dial-timeout duration        dial timeout for client connections (default 2s)
  -d, --discovery-srv string         domain name to query for SRV records describing cluster endpoints
      --discovery-srv-name string    service name to query when using DNS discovery
      --endpoints strings            gRPC endpoints (default [127.0.0.1:2379])
  -h, --help                         help for etcdctl
      --hex                          print byte strings as hex encoded strings
      --insecure-discovery           accept insecure SRV records describing cluster endpoints (default true)
      --insecure-skip-tls-verify     skip server certificate verification (CAUTION: this option should be enabled only for testing purposes)
      --insecure-transport           disable transport security for client connections (default true)
      --keepalive-time duration      keepalive time for client connections (default 2s)
      --keepalive-timeout duration   keepalive timeout for client connections (default 6s)
      --key string                   identify secure client using this TLS key file
      --max-recv-bytes int           client-side response receive limit in bytes (if 0, it defaults to "math.MaxInt32")
      --max-request-bytes int        client-side request send limit in bytes (if 0, it defaults to 2.0 MiB (2 * 1024 * 1024).)
      --password string              password for authentication (if this option is used, --user option shouldn't include password)
      --user string                  username[:password] for authentication (prompt if password is not supplied)
  -w, --write-out string             set the output format (fields, json, protobuf, simple, table) (default "simple")

Use "etcdctl [command] --help" for more information about a command.

I think the following output might be better

./bin/etcdctl --help       
A simple command line client for etcd3.

Usage:
  etcdctl [command]

Key-value commands
  compaction  Compacts the event history in etcd
  del         Removes the specified key or range of keys [key, range_end)
  get         Gets the key or a range of keys
  lease       Lease related commands. Use `etcdctl lease --help` to see subcommands
  put         Puts the given key into the store
  txn         Txn processes all the requests in one transaction
  watch       Watches events stream on keys or prefixes

Cluster maintenance commands
  alarm       Alarm related commands. Use `etcdctl alarm --help` to see subcommands
  defrag      Defragments the storage of the etcd members with given endpoints
  downgrade   Downgrade related commands. Use `etcdctl downgrade --help` to see subcommands
  endpoint    Endpoint related commands. Use `etcdctl endpoint --help` to see subcommands
  member      Membership related commands. Use `etcdctl member --help` to see subcommands
  move-leader Transfers leadership to another etcd cluster member.
  snapshot    Manages etcd node snapshots

Concurrency commands
  elect       Observes and participates in leader election
  lock        Acquires a named lock

Authentication commands
  auth        Enable or disable authentication. Use `etcdctl auth --help` to see subcommands
  role        Role related commands. Use `etcdctl role --help` to see subcommands
  user        User related commands. Use `etcdctl user --help` to see subcommands

Utility commands
  check       commands for checking properties of the etcd cluster. Use `etcdctl check --help` to see subcommands
  completion  Generate completion script
  help        Help about any command
  make-mirror Makes a mirror at the destination etcd cluster
  version     Prints the version of etcdctl
  options     Show the global flags.

Why is this needed?

• This looks simpler
• This is more consistent with kubectl's behavior

[hwdef]

I have implemented a simple version of the code for this feature. If the reviewer finds this feature useful, I am willing to continue working on it.

[siyuanfoundation]

I think it makes sense to align etcdctl with kubectl conventions with the options command, and make the help msg cleaner.
WDYT @ivanvc @serathius @jmhbnz ?

[jmhbnz]

I think it makes sense to align etcdctl with kubectl conventions with the options command, and make the help msg cleaner. WDYT @ivanvc @serathius @jmhbnz ?

Agreed - let's align with kubectl for 3.7+ if there is consensus.

[ivanvc]

I partially agree. I initially liked that the global arguments are displayed at the beginning, but after running kubectl, I do see the advantage of the compactness of that output. However, what I don't like about the current proposal is that the options command is under the Utility commands section, which makes it less noticeable.

Note that kubectl has this at the end, and not under Other Commands (our analogue to Utility commands.

$ kubectl help
kubectl controls the Kubernetes cluster manager.

 Find more information at: https://kubernetes.io/docs/reference/kubectl/overview/

...

Usage:
  kubectl [flags] [options]

Use "kubectl <command> --help" for more information about a given command.
Use "kubectl options" for a list of global command-line options (applies to all commands).

Would this be possible to implement with vanilla cobra?

[hwdef]

Note that kubectl has this at the end, and not under Other Commands (our analogue to Utility commands.

Yes, this is indeed a problem, kubectl's display is clearer.

Would this be possible to implement with vanilla cobra?

It seems that kubectl is implemented using templates, but unfortunately, I just deleted the template from etcdctl, I will try to implement this display method without templates

[hwdef]

How about this

$ ./bin/etcdctl --help 
A simple command line client for etcd3.

Usage:
  etcdctl [command]

Key-value commands
  compaction  Compacts the event history in etcd
  del         Removes the specified key or range of keys [key, range_end)
  get         Gets the key or a range of keys
  lease       Lease related commands. Use `etcdctl lease --help` to see subcommands
  put         Puts the given key into the store
  txn         Txn processes all the requests in one transaction
  watch       Watches events stream on keys or prefixes

Cluster maintenance commands
  alarm       Alarm related commands. Use `etcdctl alarm --help` to see subcommands
  defrag      Defragments the storage of the etcd members with given endpoints
  downgrade   Downgrade related commands. Use `etcdctl downgrade --help` to see subcommands
  endpoint    Endpoint related commands. Use `etcdctl endpoint --help` to see subcommands
  member      Membership related commands. Use `etcdctl member --help` to see subcommands
  move-leader Transfers leadership to another etcd cluster member.
  snapshot    Manages etcd node snapshots

Concurrency commands
  elect       Observes and participates in leader election
  lock        Acquires a named lock

Authentication commands
  auth        Enable or disable authentication. Use `etcdctl auth --help` to see subcommands
  role        Role related commands. Use `etcdctl role --help` to see subcommands
  user        User related commands. Use `etcdctl user --help` to see subcommands

Utility commands
  check       commands for checking properties of the etcd cluster. Use `etcdctl check --help` to see subcommands
  completion  Generate completion script
  help        Help about any command
  make-mirror Makes a mirror at the destination etcd cluster
  options     Show the client options
  version     Prints the version of etcdctl

Use "etcdctl [command] --help" for more information about a command.
Use "etcdctl options" for a list of global command-line options (applies to all commands).

It seems that it is possible to do it without using template. I will organize the code and create a pr later.