Tweaked usage template to resemble other popular CLI tools

[codegangsta]

This PR is mostly just a proposal to change the usage template to be a bit cleaner, more compact and readable. I took a cue from gh, terraform and kubectl and decided to go for a 2 column command/subcommand format with flags at the bottom.

@ripienaar I think this likely should live in https://github.com/choria-io/fisk and reuse/rework the column formatting funcs in that package. I also would want to change the compactWithoutFlagsOrArgs template you recently added to use a similar format to the usage template. WDYT?

Let me know and I can move this into a PR on fisk, just wanted to get your thoughts here before I do so.

 nats
usage: nats [<flags>] <command> [<args> ...]

NATS Utility

NATS Server and JetStream administration.

See 'nats cheat' for a quick cheatsheet of commands

Commands:
  account	Account information and status
  backup	JetStream configuration backup utility
  bench		Benchmark utility
  consumer	JetStream Consumer management
  context	Manage nats configuration contexts
  errors	Error code documentation
  events	Show Advisories and Events
  governor	Controls the concurrency of distributed command executions
  kv		Interacts with a JetStream based Key-Value store
  latency	Perform latency tests between two NATS servers
  object	Interacts with a JetStream based Object store
  publish	Generic data publish utility
  request	Generic request-reply request utility
  reply		Generic service reply utility
  restore	Restores a backup of JetStream configuration
  rtt		Compute round-trip time to NATS server
  schema	Schema tools
  server	Server information
  stream	JetStream Stream management
  subscribe	Generic subscription client

 nats help stream
usage: nats stream [<flags>] <command> [<args> ...]

JetStream Stream management


Subcommands:
  stream ls		List all known Streams
  stream report		Reports on Stream statistics
  stream find		Finds streams matching certain criteria
  stream info		Stream information
  stream add		Create a new Stream
  stream edit		Edits an existing stream
  stream rm		Removes a Stream
  stream purge		Purge a Stream without deleting it
  stream copy		Creates a new Stream based on the configuration of another
  stream rmm		Securely removes an individual message from a Stream
  stream view		View messages in a stream
  stream get		Retrieves a specific message from a Stream
  stream backup		Creates a backup of a Stream over the NATS network
  stream restore	Restore a Stream over the NATS network
  stream seal		Seals a stream preventing further updates
  stream cluster	Manages a clustered Stream
  stream template	Manages Stream Templates


Flags:
  -h, --help                    Show context-sensitive help
      --version                 Show application version.
  -s, --server=URL              NATS server urls ($NATS_URL)
      --user=USER               Username or Token ($NATS_USER)
      --password=PASSWORD       Password ($NATS_PASSWORD)
      --connection-name=NAME    Nickname to use for the underlying NATS Connection
      --creds=FILE              User credentials ($NATS_CREDS)
      --nkey=FILE               User NKEY ($NATS_NKEY)
      --tlscert=FILE            TLS public certificate ($NATS_CERT)
      --tlskey=FILE             TLS private key ($NATS_KEY)
      --tlsca=FILE              TLS certificate authority chain ($NATS_CA)
      --timeout=DURATION        Time to wait on responses from NATS ($NATS_TIMEOUT)
      --js-api-prefix=PREFIX    Subject prefix for access to JetStream API
      --js-event-prefix=PREFIX  Subject prefix for access to JetStream Advisories
      --js-domain=DOMAIN        JetStream domain to access
      --inbox-prefix=PREFIX     Custom inbox prefix to use for inboxes
      --context=NAME            Configuration context ($NATS_CONTEXT)
      --trace                   Trace API interactions
  -a, --all                     When listing or selecting streams show all streams including system ones

[ripienaar]

Looks pretty yeah, just means we have to. make sure we keep the descriptions short.

If you want to contribute to fisk you can, but we can also try it here if easier

[ripienaar]

Ideally we also seperate the command specific flags from the top level noise - but kingpin and therefor fisk doesnt have data to make that possible

[codegangsta]

Yeah that was next on my list after this :)

[codegangsta]

@ripienaar I think it will be cleaner if this was in fisk. Are you okay with this format affecting choria tooling? Otherwise I can just bake in a couple more hooks in fisk and make most of the changes here

[ripienaar]

Add it to fisk but some new name - leaving default as is. We'll opt this project into that new format (perhaps under a feature flag to preview?)

[codegangsta]

Cool. Sounds good

[codegangsta]

@ripienaar This PR now relies on choria-io/fisk#23, but ended up being a much cleaner implementation. I also was able to separate global and local flags and it feels a lot more ergonomic to me.

[ripienaar]

yeah looks great, so update this PR to go get that latest commit on fisk and use that here and we can merge that so we have a few days to test before next release

[codegangsta]

@ripienaar Thanks for looking at this today. Should be all upgraded to the latest fisk commit

[ripienaar]

very nice, thank you