CLI: empty `podman` command isn't helpful or encouraging

[allanday]

Is this a BUG REPORT or FEATURE REQUEST? (leave only one on its own line)

/kind bug

Description

If someone is starting out with Podman, they might well run podman without any additional commands. Currently the response from the CLI is blunt and unhelpful; it doesn't make you want to use the tool.

For comparison, git shows the output of git --help in this situation. oc gives you a helpful description of what it is, and some pointers on how to get started.

Steps to reproduce the issue:

Run podman.

Describe the results you received:

CLI returns;

Error: missing command 'podman COMMAND'
Try 'podman --help' for more information.

Describe the results you expected:

Details to help me get started.

Output of podman version:

Version:      3.0.1
API Version:  3.0.0
Go Version:   go1.15.8
Built:        Fri Feb 19 16:56:17 2021
OS/Arch:      linux/amd64

Have you tested with the latest version of Podman and have you checked the Podman Troubleshooting Guide?

Yes, no.

[vrothberg]

Thanks for reaching out, @allanday!

I like the idea of displaying podman --help directly. @baude @mheon WDYT?

[baude]

this has been a sore spot for me ... but iirc @rhatdan has objections to it. Maybe he has since changed his mind.

[rhatdan]

I would be fine with a naked command doing this, but the problem is with actual errors like

podman foobar

And this throws a wall of help information at you hiding that foobar is not a valid command.

BTW Most of coreutils work just like podman.

$ podman
Error: missing command 'podman COMMAND'
Try 'podman --help' for more information.

Tells the user pretty much what is required.

As opposed to:

$ podman
Error: missing command 'podman COMMAND'
Manage pods, containers and images

Usage:
  podman [options] [command]

Available Commands:
  attach      Attach to a running container
  auto-update Auto update containers according to their auto-update policy
  build       Build an image using instructions from Containerfiles
  commit      Create new image based on the changed container
  container   Manage containers
  cp          Copy files/folders between a container and the local filesystem
  create      Create but do not start a container
  diff        Display the changes to the object's file system
  events      Show podman events
  exec        Run a process in a running container
  export      Export container's filesystem contents as a tar archive
  generate    Generate structured data based on containers and pods.
  healthcheck Manage health checks on containers
  help        Help about any command
  history     Show history of a specified image
  image       Manage images
  images      List images in local storage
  import      Import a tarball to create a filesystem image
  info        Display podman system information
  init        Initialize one or more containers
  inspect     Display the configuration of object denoted by ID
  kill        Kill one or more running containers with a specific signal
  load        Load image(s) from a tar archive
  login       Login to a container registry
  logout      Logout of a container registry
  logs        Fetch the logs of one or more containers
  manifest    Manipulate manifest lists and image indexes
  mount       Mount a working container's root filesystem
  network     Manage networks
  pause       Pause all the processes in one or more containers
  play        Play a pod and its containers from a structured file.
  pod         Manage pods
  port        List port mappings or a specific mapping for the container
  ps          List containers
  pull        Pull an image from a registry
  push        Push an image to a specified destination
  rename      Rename an existing container
  restart     Restart one or more containers
  rm          Remove one or more containers
  rmi         Removes one or more images from local storage
  run         Run a command in a new container
  save        Save image(s) to an archive
  search      Search registry for image
  start       Start one or more containers
  stats       Display a live stream of container resource usage statistics
  stop        Stop one or more containers
  system      Manage podman
  tag         Add an additional name to a local image
  top         Display the running processes of a container
  unmount     Unmounts working container's root filesystem
  unpause     Unpause the processes in one or more containers
  unshare     Run a command in a modified user namespace
  untag       Remove a name from a local image
  version     Display the Podman Version Information
  volume      Manage volumes
  wait        Block on one or more containers

Options:
      --cgroup-manager string      Cgroup manager to use ("cgroupfs"|"systemd") (default "systemd")
      --cni-config-dir string      Path of the configuration directory for CNI networks
      --conmon string              Path of the conmon binary
  -c, --connection string          Connection to use for remote Podman service
      --events-backend string      Events backend to use ("file"|"journald"|"none") (default "journald")
      --help                       Help for podman
      --hooks-dir strings          Set the OCI hooks directory path (may be set multiple times) (default [/usr/share/containers/oci/hooks.d])
      --identity string            path to SSH identity file, (CONTAINER_SSHKEY)
      --log-level string           Log messages above specified level (debug, info, warn, warning, error, fatal, panic) (default "warn")
      --namespace string           Set the libpod namespace, used to create separate views of the containers and pods on the system
      --network-cmd-path string    Path to the command for configuring the network
  -r, --remote                     Access remote Podman service (default false)
      --root string                Path to the root directory in which data, including images, is stored
      --runroot string             Path to the 'run directory' where all state information is stored
      --runtime string             Path to the OCI-compatible binary used to run containers, default is /usr/bin/runc
      --runtime-flag stringArray   add global flags for the container runtime
      --storage-driver string      Select which storage driver is used to manage storage of images and containers (default is overlay)
      --storage-opt stringArray    Used to pass an option to the storage driver
      --syslog                     Output logging information to syslog as well as the console (default false)
      --tmpdir string              Path to the tmp directory for libpod state content.
                                   
                                   Note: use the environment variable 'TMPDIR' to change the temporary storage location for container images, '/var/tmp'.
                                   
      --url string                 URL to access Podman service (CONTAINER_HOST) (default "unix:/run/user/3267/podman/podman.sock")
  -v, --version                    version for podman

Which scrolls the error right off the top of the screen.

 $ grep
Usage: grep [OPTION]... PATTERNS [FILE]...
Try 'grep --help' for more information.
$ cp
cp: missing file operand
Try 'cp --help' for more information.
$ rm
rm: missing operand
Try 'rm --help' for more information.
...

[rhatdan]

BTW Docker does show help on a naked docker, and shows the nice errors I like on bad commands.

$ docker

Usage:  docker [OPTIONS] COMMAND

A self-sufficient runtime for containers

Options:
      --config string      Location of client config files (default "/home/dwalsh/.docker")
  -c, --context string     Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with "docker context use")
  -D, --debug              Enable debug mode
  -H, --host list          Daemon socket(s) to connect to
  -l, --log-level string   Set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info")
      --tls                Use TLS; implied by --tlsverify
      --tlscacert string   Trust certs signed only by this CA (default "/home/dwalsh/.docker/ca.pem")
      --tlscert string     Path to TLS certificate file (default "/home/dwalsh/.docker/cert.pem")
      --tlskey string      Path to TLS key file (default "/home/dwalsh/.docker/key.pem")
      --tlsverify          Use TLS and verify the remote
  -v, --version            Print version information and quit

Management Commands:
  app*        Docker App (Docker Inc., v0.9.1-beta3)
  builder     Manage builds
  buildx*     Build with BuildKit (Docker Inc., v0.5.1-docker)
  config      Manage Docker configs
  container   Manage containers
  context     Manage contexts
  image       Manage images
  manifest    Manage Docker image manifests and manifest lists
  network     Manage networks
  node        Manage Swarm nodes
  plugin      Manage plugins
  secret      Manage Docker secrets
  service     Manage services
  stack       Manage Docker stacks
  swarm       Manage Swarm
  system      Manage Docker
  trust       Manage trust on Docker images
  volume      Manage volumes

Commands:
  attach      Attach local standard input, output, and error streams to a running container
  build       Build an image from a Dockerfile
  commit      Create a new image from a container's changes
  cp          Copy files/folders between a container and the local filesystem
  create      Create a new container
  diff        Inspect changes to files or directories on a container's filesystem
  events      Get real time events from the server
  exec        Run a command in a running container
  export      Export a container's filesystem as a tar archive
  history     Show the history of an image
  images      List images
  import      Import the contents from a tarball to create a filesystem image
  info        Display system-wide information
  inspect     Return low-level information on Docker objects
  kill        Kill one or more running containers
  load        Load an image from a tar archive or STDIN
  login       Log in to a Docker registry
  logout      Log out from a Docker registry
  logs        Fetch the logs of a container
  pause       Pause all processes within one or more containers
  port        List port mappings or a specific mapping for the container
  ps          List containers
  pull        Pull an image or a repository from a registry
  push        Push an image or a repository to a registry
  rename      Rename a container
  restart     Restart one or more containers
  rm          Remove one or more containers
  rmi         Remove one or more images
  run         Run a command in a new container
  save        Save one or more images to a tar archive (streamed to STDOUT by default)
  search      Search the Docker Hub for images
  start       Start one or more stopped containers
  stats       Display a live stream of container(s) resource usage statistics
  stop        Stop one or more running containers
  tag         Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
  top         Display the running processes of a container
  unpause     Unpause all processes within one or more containers
  update      Update configuration of one or more containers
  version     Show the Docker version information
  wait        Block until one or more containers stop, then print their exit codes

Run 'docker COMMAND --help' for more information on a command.

To get more help with docker, check out our guides at https://docs.docker.com/go/guides/

And

$ docker foobar
docker: 'foobar' is not a docker command.
See 'docker --help'

[allanday]

For the naked single command, it's worth considering what oc does:

$ oc
OpenShift Client 

This client helps you develop, build, deploy, and run your applications on any OpenShift or Kubernetes compatible platform. It also includes the administrative commands for managing a cluster under the 'adm' subcommand.

To create a new application, login to your server and then run new-app: 

  oc login https://mycluster.mycompany.com
  oc new-app centos/ruby-25-centos7~https://github.com/sclorg/ruby-ex.git
  oc logs -f bc/ruby-ex
  
This will create an application based on the Docker image 'centos/ruby-25-centos7' that builds the source code from GitHub. A build will start automatically, push the resulting image to the registry, and a deployment will roll that change out in your project. 

Once your application is deployed, use the status, describe, and get commands to see more about the created components: 

  oc status
  oc describe deploymentconfig ruby-ex
  oc get pods
  
To make this application visible outside of the cluster, use the expose command on the service we just created to create a 'route' (which will connect your application over the HTTP port to a public domain name). 

  oc expose svc/ruby-ex
  oc status
  
You should now see the URL the application can be reached at. 

To see the full list of commands supported, run 'oc --help'

This is clearly focused on initial user onboarding, which is what I was primarily interested in for this issue: if we want to funnel people into using Podman, then providing help and pointers is a good idea.

From what I can tell, there are four potential options for a naked podman command:

1. Current behaviour - throw an error, point to --help
2. Show the output of --help
3. Show an abbreviated version of --help, with common commands and a suggestion to use --help for more
4. Show a short intro to podman, similar to oc

In my view 2-4 would be better than the current response, from the perspective of new user onboarding. If there's a concern about the length of --help (which I get), then 3 or 4 could be alternatives.

I hadn't intended this issue to apply to the unrecognised command case, but if we are going to consider that, then git's approach of making a suggestion seems like a good one:

$ git rebras
git: 'rebras' is not a git command. See 'git --help'.

The most similar command is
	rebase

I've certainly found this to be helpful in the past.

[github-actions]

A friendly reminder that this issue had no activity for 30 days.

[rhatdan]

Interested in opening a PR?
This would seem to be a good first issue.

[hzliangbin]

/assign

[github-actions]

A friendly reminder that this issue had no activity for 30 days.