Tracking: Review the interface of the CLI

We should review the interface of the CLI and investigate whether there are any changes we would like to make in order to make it more understandable or intuitive. Then, we need to update our high-level documentation to reflect any changes in the command-line options. We may also want to consider adding doc tests to the CLI crate to make sure we get a build break whenever we make a breaking change to the CLI.

We should evaluate the following aspects of the CLI:

[ ] What is the minimum key functionality exposed?
[ ] What is the most logical organization of this functionality?
[ ] How can this functionality be made consistent with the other client APIs such as the Rust crate and Node package?

After evaluating the interface and deciding on any changes, we should do the following:

[ ] Update CLI documentation #63
[ ] Write tests for CLI regression
[ ] Update CLI help messages

Change Proposals

I'm going to break proposals out into their own issues in order to address them individually. Please see the following issues for discussion:

[ ] Proposal 1 (#367): Changing the CLI action/object order
- [ ] Accepted
[ ] Proposal 2: Use global args to reduce noise in help menus
- [x] Accepted
- [ ] Done

Examining existing commands

Since our subcommands are so nested, it can be hard to think about how many individual commands we really have. Here I lay out all of the "leaf" commands, the ones that perform actions when given the right arguments. This will give us a good starting point when deciding if any of these need rearranging.

fluvio consume                           Reads messages from a topic/partition
fluvio produce                           Writes messages to a topic/partition
fluvio version                           Prints the current fluvio version information
fluvio spu list                          List custom & managed SPUs
fluvio spu-group create                  Create managed SPU group
fluvio spu-group delete                  Delete managed SPU group
fluvio spu-group list                    List managed SPU groups
fluvio custom-spu register               Create custom SPU
fluvio custom-spu unregister             Delete custom SPU
fluvio custom-spu list                   List custom SPUs
fluvio topic create                      Creates a topic
fluvio topic delete                      Deletes a topic
fluvio topic describe                    Shows details of a topic
fluvio topic list                        Shows all topics
fluvio partition list                    Show all partitions
fluvio profile current                   Display the current context
fluvio profile delete                    Delete the named profile
fluvio profile delete-cluster            Delete the named cluster
fluvio profile switch                    Switch to the named profile
fluvio profile sync k8                   sync profile from kubernetes cluster
fluvio profile sync local                sync profile from local cluster
fluvio profile sync cloud                sync profile from Fluvio Cloud
fluvio profile view                      Display entire configuration
fluvio cluster set-minikube-context      set my own context
fluvio cluster install                   install cluster
fluvio cluster uninstall                 uninstall cluster
fluvio cluster check                     perform checks
fluvio cluster releases list             release information

Examining existing arguments

For each subcommand leaf, I'm going to list the possible arguments for that command. This will help us to see whether there are any good candidates for global arguments or other factorizations

fluvio consume                           Reads messages from a topic/partition
  FLAGS:
    -B, --from-beginning        Start reading from beginning
    -d, --disable-continuous    disable continuous processing of messages
    -s, --suppress-unknown      Suppress items items that have an unknown output type
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -p, --partition <integer>          Partition id [default: 0]
    -o, --offset <integer>             Offsets can be positive or negative. (Syntax for negative offset: --offset="-1")
    -b, --maxbytes <integer>           Maximum number of bytes to be retrieved
    -O, --output <type>                Output [default: dynamic]  [possible values: dynamic, text, binary, json, raw]
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

  ARGS:
    <string>    Topic name

fluvio produce                           Writes messages to a topic/partition
  FLAGS:
    -C, --continuous            Send messages in an infinite loop
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -p, --partition <integer>           Partition id [default: 0]
    -l, --record-per-line <filename>    Each line is a Record
    -r, --record-file <filename>...     Entire file is a Record (multiple)
    -c, --cluster <host:port>           Address of cluster
        --domain <domain>               Required if client cert is used
        --ca-cert <ca-cert>             Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>     Path to TLS client certificate
        --client-key <client-key>       Path to TLS client private key
    -P, --profile <profile>

  ARGS:
    <topic>    Topic name

fluvio version                           Prints the current fluvio version information

fluvio spu list                          List custom & managed SPUs
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -O, --output <type>                Output [possible values: table, yaml, json]
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

fluvio spu-group create                  Create managed SPU group
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -r, --replicas <integer>           SPU replicas [default: 1]
        --min-id <min-id>              Minimum SPU id (default: 1) [default: 1]
        --rack <string>                Rack name
        --storage-size <string>        storage size
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

  ARGS:
    <string>    Managed SPU group name

fluvio spu-group delete                  Delete managed SPU group
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -n, --name <string>                Managed SPU group name
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

fluvio spu-group list                    List managed SPU groups
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -O, --output <type>                Output [possible values: table, yaml, json]
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

fluvio custom-spu register               Create custom SPU
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -i, --id <id>                       SPU id
    -n, --name <string>                 SPU name
    -r, --rack <string>                 Rack name
    -p, --public-server <host:port>     Public server::port
    -v, --private-server <host:port>    Private server::port
    -c, --cluster <host:port>           Address of cluster
        --domain <domain>               Required if client cert is used
        --ca-cert <ca-cert>             Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>     Path to TLS client certificate
        --client-key <client-key>       Path to TLS client private key
    -P, --profile <profile>

fluvio custom-spu unregister             Delete custom SPU
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -i, --id <id>                      SPU id
    -n, --name <string>                SPU name
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

fluvio custom-spu list                   List custom SPUs
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -O, --output <type>                Output [possible values: table, yaml, json]
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

fluvio topic create                      Creates a topic
  FLAGS:
    -i, --ignore-rack-assignment    Ignore racks while computing replica assignment
    -d, --dry-run                   Validates configuration, does not provision
        --tls                       Enable TLS
        --enable-client-cert        TLS: use client cert

  OPTIONS:
    -p, --partitions <partitions>           Number of partitions [default: 1]
    -r, --replication <integer>             Replication factor per partition [default: 1]
    -f, --replica-assignment <file.json>    Replica assignment file
    -c, --cluster <host:port>               Address of cluster
        --domain <domain>                   Required if client cert is used
        --ca-cert <ca-cert>                 Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>         Path to TLS client certificate
        --client-key <client-key>           Path to TLS client private key
    -P, --profile <profile>

  ARGS:
    <topic-name>    Topic name

fluvio topic delete                      Deletes a topic
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

  ARGS:
    <string>

fluvio topic describe                    Shows details of a topic
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -O, --output <type>                Output [possible values: table, yaml, json]
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

  ARGS:
    <string>    Topic filter

fluvio topic list                        Shows all topics
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -o, --output <type>                Output [possible values: table, yaml, json]
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

fluvio partition list                    Show all partitions
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -O, --output <type>                Output [possible values: table, yaml, json]
    -c, --cluster <host:port>          Address of cluster
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key
    -P, --profile <profile>

fluvio profile current                   Display the current context

fluvio profile delete                    Delete the named profile
  ARGS:
    <profile name>

fluvio profile delete-cluster            Delete the named cluster
FLAGS:
    -f, --force    Deletes a cluster even if its active

ARGS:
    <cluster name>    The name of a cluster connection to delete

fluvio profile switch                    Switch to the named profile
  ARGS:
    <profile name>

fluvio profile sync k8
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
    -n, --namespace <namespace>        kubernetes namespace,
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key

  ARGS:
    <name>    profile name

fluvio profile sync local
  FLAGS:
        --tls                   Enable TLS
        --enable-client-cert    TLS: use client cert

  OPTIONS:
        --domain <domain>              Required if client cert is used
        --ca-cert <ca-cert>            Path to TLS ca cert, required when client cert is enabled
        --client-cert <client-cert>    Path to TLS client certificate
        --client-key <client-key>      Path to TLS client private key

  ARGS:
    <host:port>     [default: localhost:9003]

fluvio profile sync cloud
  OPTIONS:
    -e, --email <email>      Fluvio Cloud email to use for logging in
        --remote <remote>    Fluvio Cloud remote address to use

fluvio profile view                      Display entire configuration

fluvio cluster set-minikube-context      set my own context
  OPTIONS:
        --name <name>    set context name

fluvio cluster install                   install cluster
  FLAGS:
        --develop                  use local image
        --skip-profile-creation
        --sys                      installing sys
        --local                    install local spu/sc(custom)
        --tls                      Whether to use TLS

  OPTIONS:
        --chart-version <chart-version>      k8: use specific chart version [default: 0.6.0-alpha.2]
        --image-version <image-version>      k8: use specific image version
        --registry <registry>                k8: use custom docker registry
        --namespace <namespace>              k8 [default: default]
        --group-name <group-name>            k8 [default: main]
        --install-name <install-name>        helm chart installation name [default: fluvio]
        --chart-location <chart-location>    Local path to a helm chart to install
        --cloud <cloud>                      k8 [default: minikube]
        --spu <spu>                          number of SPU [default: 1]
        --rust-log <rust-log>                RUST_LOG options
        --log-dir <log-dir>                  log dir
        --domain <domain>                    TLS: domain
        --ca-cert <ca-cert>                  TLS: ca cert
        --client-cert <client-cert>          TLS: client cert
        --client-key <client-key>            TLS: client key
        --server-cert <server-cert>          TLS: path to server certificate
        --server-key <server-key>            TLS: path to server private key

fluvio cluster uninstall                 uninstall cluster
  FLAGS:
        --no-wait    don't wait for clean up
        --local      uninstall local spu/sc(custom)
        --sys        removing sys chart

  OPTIONS:
        --namespace <namespace>     [default: default]
        --name <name>               [default: fluvio]

fluvio cluster check                     perform checks
  FLAGS:
        --pre-install    run pre-install checks

fluvio cluster releases list             release information

infinyon / fluvio