kctrl package output when wrong command/input should be consistent

[jorgemoralespou]

What steps did you take:

kctrl
kctrl helps to manage packages and repositories on your Kubernetes cluster (package, version)

Usage:
  kctrl [flags]
  kctrl [command]

Package Commands:
  package     Package (available, install, installed, repository)

Available/Other Commands:
  help        Help about any command
  version     Print client version

Flags:
      --color                       Set color output (default true)
      --column strings              Filter to show only given columns
      --debug                       Include debug output
  -h, --help                        help for kctrl
      --json                        Output as JSON
      --kube-api-burst int          Set Kubernetes API client burst limit (default 1000)
      --kube-api-qps float32        Set Kubernetes API client QPS limit (default 1000)
      --kubeconfig string           Path to the kubeconfig file ($KCTRL_KUBECONFIG)
      --kubeconfig-context string   Kubeconfig context override ($KCTRL_KUBECONFIG_CONTEXT)
      --kubeconfig-yaml string      Kubeconfig contents as YAML ($KCTRL_KUBECONFIG_YAML)
      --tty                         Force TTY-like output (default true)
  -v, --version                     version for kctrl
  -y, --yes                         Assume yes for any prompt

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

kctrl: Error: Invalid command - see available commands/subcommands above
❯ kctrl package
kctrl: Error: Use one of available subcommands: available, install, installed, repository
❯ kctrl package get
kctrl: Error: Use one of available subcommands: available, install, installed, repository

What happened: kctrl without any command, prints help for command and output error, but kctrl package without any subcommand prints only error, and not help message that will help understand subcommand, flags, etc...

What did you expect: I would expect the help to be provided so that I don't need to fail or have to do an additional explicit -h call to understand usage.

Environment:

• kapp Controller version (execute kubectl get deployment -n kapp-controller kapp-controller -o yaml and the annotation is kbld.k14s.io/images): kctrl version 0.34.0
• Kubernetes version (use kubectl version)

---

Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible" 👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

[100mik]

Out of curiosity, which one of these would you prefer? (the more verbose help section, or a more direct error message)

[jorgemoralespou]

the more verbose output, which aligns with the behavior of most related CLIs like tanzu, pack, and many more in the k8s space. It seems current behavior is common to other Carvel CLIs (kapp at least) :-( As mentioned, this output makes you issue an additional invocation:

• kctrl does not provide any help on error, so requires always an additional invocation:

$ kctrl package available get
kctrl: Error: Expected package name to be non-empty

• Docker provides an intermediate behavior where it doesn't print verbose help, but gives enough information to not require --help unless the format of params is unknown. For more complex commands, you still need to issue --help to understand how to use it.

$ docker port
"docker port" requires at least 1 and at most 2 arguments.
See 'docker port --help'.

Usage:  docker port CONTAINER [PRIVATE_PORT[/PROTO]]

List port mappings or a specific mapping for the container

$ docker run
"docker run" requires at least 1 argument.
See 'docker run --help'.

Usage:  docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Run a command in a new container

• pack (and other tools) does provide enough information to not require additional usage.

$ pack builder create
Error: accepts 1 arg(s), received 0
Usage:
  pack builder create <image-name> --config <builder-config-path> [flags]

Examples:
pack builder create my-builder:bionic --config ./builder.toml

Flags:
  -c, --config string        Path to builder TOML file (required)
  -h, --help                 Help for 'create'
      --publish              Publish to registry
      --pull-policy string   Pull policy to use. Accepted values are always, never, and if-not-present. The default is always

Global Flags:
      --no-color     Disable color output
  -q, --quiet        Show less output
      --timestamps   Enable timestamps in output
  -v, --verbose      Show more output

[cppforlife]

It seems current behavior is common to other Carvel CLIs

we have received feedback before that dumping help text is confusing because it's just too much -- i agree with that assestment. the thinking is that in most cases user just forgot to add a flag/arg -- they know how to do it, but just forgot, or they want to see more targeted suggestion rather than a wall of help text. it would be useful to provide a bit more info in error messages of what is required -- specifically which flag should i provide.

[jorgemoralespou]

Well, from a UX perspective, there's tradeoffs between usefulness and confusionness. Usefulness is when the tool helps you as it's difficult to use so it guide you to a correct use with the minimal amount of effort. Confusionness is when it gets always in the middle.

If you're an advanced user, you will most likely never miss a command/flag and if you do it will be very few times, so you will be confused very little. If you're a newbie user, you might miss a command/flag many times, so you will be helped a lot.

Sometimes our engineer eyes are not the best eyes to look at things, if we're targeting non-engineer users. It obviously depends on the tools, but from what I understand kctrl is a tool to help users manage (install, update, delete) packages on a cluster, so probably not same users as kapp/ytt/imgpkg users. Although I still find those, even if consistent with this tool, confusing to use.

[cppforlife]

i think we are saying the same thing but coming to different conclusions:

output below to me is not "helping the user", it just dumps a pile of text. in fact ive seen bunch of times where people when faced with below experience would be confused of what they have done wrong because it just looks like a wall of text.

$ pack builder create
Error: accepts 1 arg(s), received 0
Usage:
  pack builder create <image-name> --config <builder-config-path> [flags]

Examples:
pack builder create my-builder:bionic --config ./builder.toml

Flags:
  -c, --config string        Path to builder TOML file (required)
  -h, --help                 Help for 'create'
      --publish              Publish to registry
      --pull-policy string   Pull policy to use. Accepted values are always, never, and if-not-present. The default is always

Global Flags:
      --no-color     Disable color output
  -q, --quiet        Show less output
      --timestamps   Enable timestamps in output
  -v, --verbose      Show more output

docker cli approach seems like a reasonable design choice that still focuses on the error but also provides just enough context to know what's going on / what they can do to do more.

[renuy]

Still under discussion.