Better usage synopses for subcommands

Conceptually simple: include, where applicable, a brief description of command-line options for each subcommand. Signed-off-by: Ed Santiago <santiago@redhat.com>
2025-10-18 11:42:55 +08:00 · 2019-02-26 14:11:27 -07:00
parent ee667dcf97
commit a20ff42134
58 changed files with 65 additions and 61 deletions
--- a/cmd/podman/attach.go
+++ b/cmd/podman/attach.go
@ -14,7 +14,7 @@ var (
 	attachCommand     cliconfig.AttachValues
 	attachDescription = "The podman attach command allows you to attach to a running container using the container's ID or name, either to view its ongoing output or to control it interactively."
 	_attachCommand    = &cobra.Command{
-		Use:   "attach",
+		Use:   "attach [flags] CONTAINER",
 		Short: "Attach to a running container",
 		Long:  attachDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/build.go
+++ b/cmd/podman/build.go
@ -27,7 +27,7 @@ var (
 	namespaceValues  buildahcli.NameSpaceResults

 	_buildCommand = &cobra.Command{
-		Use:   "build",
+		Use:   "build [flags] CONTEXT",
 		Short: "Build an image using instructions from Dockerfiles",
 		Long:  buildDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/checkpoint.go
+++ b/cmd/podman/checkpoint.go
@ -21,7 +21,7 @@ var (
   Checkpoints one or more running containers. The container name or ID can be used.
 `
 	_checkpointCommand = &cobra.Command{
-		Use:   "checkpoint",
+		Use:   "checkpoint [flags] CONTAINER [CONTAINER...]",
 		Short: "Checkpoints one or more containers",
 		Long:  checkpointDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/cleanup.go
+++ b/cmd/podman/cleanup.go
@ -18,7 +18,7 @@ var (
   Cleans up mount points and network stacks on one or more containers from the host. The container name or ID can be used. This command is used internally when running containers, but can also be used if container cleanup has failed when a container exits.
 `
 	_cleanupCommand = &cobra.Command{
-		Use:   "cleanup",
+		Use:   "cleanup [flags] CONTAINER [CONTAINER...]",
 		Short: "Cleanup network and mountpoints of one or more containers",
 		Long:  cleanupDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/commit.go
+++ b/cmd/podman/commit.go
@ -25,7 +25,7 @@ var (
 	 and make changes to the instructions with the --change flag.`

 	_commitCommand = &cobra.Command{
-		Use:   "commit",
+		Use:   "commit [flags] CONTAINER IMAGE",
 		Short: "Create new image based on the changed container",
 		Long:  commitDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/cp.go
+++ b/cmd/podman/cp.go
@ -29,7 +29,7 @@ var (

 	cpDescription = "Copy files/folders between a container and the local filesystem"
 	_cpCommand    = &cobra.Command{
-		Use:   "cp",
+		Use:   "cp [flags] SRC_PATH DEST_PATH",
 		Short: "Copy files/folders between a container and the local filesystem",
 		Long:  cpDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/create.go
+++ b/cmd/podman/create.go
@ -42,7 +42,7 @@ var (
 		" any time with the podman start <container_id> command. The container" +
 		" will be created with the initial state 'created'."
 	_createCommand = &cobra.Command{
-		Use:   "create",
+		Use:   "create [flags] IMAGE [COMMAND [ARG...]]",
 		Short: "Create but do not start a container",
 		Long:  createDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/diff.go
+++ b/cmd/podman/diff.go
@ -38,7 +38,7 @@ var (
 	container or image will be compared to its parent layer`)

 	_diffCommand = &cobra.Command{
-		Use:   "diff",
+		Use:   "diff [flags] CONTAINER | IMAGE",
 		Short: "Inspect changes on container's file systems",
 		Long:  diffDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/exec.go
+++ b/cmd/podman/exec.go
@ -21,7 +21,7 @@ var (
 	Run a command in a running container
 `
 	_execCommand = &cobra.Command{
-		Use:   "exec",
+		Use:   "exec [flags] CONTAINER [COMMAND [ARG...]]",
 		Short: "Run a process in a running container",
 		Long:  execDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/exists.go
+++ b/cmd/podman/exists.go
@ -32,7 +32,7 @@ var (
 	Check if a pod exists in local storage
 `
 	_imageExistsCommand = &cobra.Command{
-		Use:   "exists",
+		Use:   "exists IMAGE",
 		Short: "Check if an image exists in local storage",
 		Long:  imageExistsDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
@ -44,7 +44,7 @@ var (
 	}

 	_containerExistsCommand = &cobra.Command{
-		Use:   "exists",
+		Use:   "exists CONTAINER",
 		Short: "Check if a container exists in local storage",
 		Long:  containerExistsDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
@ -57,7 +57,7 @@ var (
 	}

 	_podExistsCommand = &cobra.Command{
-		Use:   "exists",
+		Use:   "exists POD",
 		Short: "Check if a pod exists in local storage",
 		Long:  podExistsDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
@ -71,10 +71,13 @@ var (

 func init() {
 	imageExistsCommand.Command = _imageExistsCommand
+	imageExistsCommand.DisableFlagsInUseLine = true
 	imageExistsCommand.SetUsageTemplate(UsageTemplate())
 	containerExistsCommand.Command = _containerExistsCommand
+	containerExistsCommand.DisableFlagsInUseLine = true
 	containerExistsCommand.SetUsageTemplate(UsageTemplate())
 	podExistsCommand.Command = _podExistsCommand
+	podExistsCommand.DisableFlagsInUseLine = true
 	podExistsCommand.SetUsageTemplate(UsageTemplate())
 }

--- a/cmd/podman/export.go
+++ b/cmd/podman/export.go
@ -17,7 +17,7 @@ var (
 		" and saves it on the local machine."

 	_exportCommand = &cobra.Command{
-		Use:   "export",
+		Use:   "export [flags] CONTAINER",
 		Short: "Export container's filesystem contents as a tar archive",
 		Long:  exportDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/generate_kube.go
+++ b/cmd/podman/generate_kube.go
@ -17,7 +17,7 @@ var (
 	containerKubeCommand     cliconfig.GenerateKubeValues
 	containerKubeDescription = "Generate Kubernetes Pod YAML"
 	_containerKubeCommand    = &cobra.Command{
-		Use:   "kube",
+		Use:   "kube CONTAINER | POD",
 		Short: "Generate Kubernetes pod YAML for a container or pod",
 		Long:  containerKubeDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/history.go
+++ b/cmd/podman/history.go
@ -40,7 +40,7 @@ var (
 	historyDescription = "Displays the history of an image. The information can be printed out in an easy to read, " +
 		"or user specified format, and can be truncated."
 	_historyCommand = &cobra.Command{
-		Use:   "history",
+		Use:   "history [flags] IMAGE",
 		Short: "Show history of a specified image",
 		Long:  historyDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/import.go
+++ b/cmd/podman/import.go
@ -17,7 +17,7 @@ var (
 	 Optionally tag the image. You can specify the instructions using the --change option.
 	`
 	_importCommand = &cobra.Command{
-		Use:   "import",
+		Use:   "import [flags] PATH [REFERENCE]",
 		Short: "Import a tarball to create a filesystem image",
 		Long:  importDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/inspect.go
+++ b/cmd/podman/inspect.go
@ -26,7 +26,7 @@ var (

 	inspectDescription = "This displays the low-level information on containers and images identified by name or ID. By default, this will render all results in a JSON array. If the container and image have the same name, this will return container JSON for unspecified type."
 	_inspectCommand    = &cobra.Command{
-		Use:   "inspect",
+		Use:   "inspect [flags] CONTAINER | IMAGE",
 		Short: "Display the configuration of a container or image",
 		Long:  inspectDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/kill.go
+++ b/cmd/podman/kill.go
@ -20,7 +20,7 @@ var (

 	killDescription = "The main process inside each container specified will be sent SIGKILL, or any signal specified with option --signal."
 	_killCommand    = &cobra.Command{
-		Use:   "kill",
+		Use:   "kill [flags] CONTAINER [CONTAINER...]",
 		Short: "Kill one or more running containers with a specific signal",
 		Long:  killDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/load.go
+++ b/cmd/podman/load.go
@ -17,7 +17,7 @@ var (

 	loadDescription = "Loads the image from docker-archive stored on the local machine."
 	_loadCommand    = &cobra.Command{
-		Use:   "load",
+		Use:   "load [flags] [PATH]",
 		Short: "Load an image from docker archive",
 		Long:  loadDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/login.go
+++ b/cmd/podman/login.go
@ -21,7 +21,7 @@ var (

 	loginDescription = "Login to a container registry on a specified server."
 	_loginCommand    = &cobra.Command{
-		Use:   "login",
+		Use:   "login [flags] REGISTRY",
 		Short: "Login to a container registry",
 		Long:  loginDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/logout.go
+++ b/cmd/podman/logout.go
@ -14,7 +14,7 @@ var (
 	logoutCommand     cliconfig.LogoutValues
 	logoutDescription = "Remove the cached username and password for the registry."
 	_logoutCommand    = &cobra.Command{
-		Use:   "logout",
+		Use:   "logout [flags] REGISTRY",
 		Short: "Logout of a container registry",
 		Long:  logoutDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/logs.go
+++ b/cmd/podman/logs.go
@ -18,7 +18,7 @@ var (
 	logsDescription = "The podman logs command batch-retrieves whatever logs are present for a container at the time of execution.  This does not guarantee execution" +
 		"order when combined with podman run (i.e. your run may not have generated any logs at the time you execute podman logs"
 	_logsCommand = &cobra.Command{
-		Use:   "logs",
+		Use:   "logs [flags] CONTAINER",
 		Short: "Fetch the logs of a container",
 		Long:  logsDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/mount.go
+++ b/cmd/podman/mount.go
@ -26,7 +26,7 @@ var (
 `

 	_mountCommand = &cobra.Command{
-		Use:   "mount",
+		Use:   "mount [flags] CONTAINER",
 		Short: "Mount a working container's root filesystem",
 		Long:  mountDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pause.go
+++ b/cmd/podman/pause.go
@ -20,7 +20,7 @@ var (
   Pauses one or more running containers.  The container name or ID can be used.
 `
 	_pauseCommand = &cobra.Command{
-		Use:   "pause",
+		Use:   "pause [flags] CONTAINER [CONTAINER...]",
 		Short: "Pause all the processes in one or more containers",
 		Long:  pauseDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
@ -30,7 +30,7 @@ var (
 		},
 		Example: `podman pause mywebserver
  podman pause 860a4b23
-  podman stop -a`,
+  podman pause -a`,
 	}
 )

--- a/cmd/podman/play_kube.go
+++ b/cmd/podman/play_kube.go
@ -29,7 +29,7 @@ var (
 	playKubeCommand     cliconfig.KubePlayValues
 	playKubeDescription = "Play a Pod and its containers based on a Kubrernetes YAML"
 	_playKubeCommand    = &cobra.Command{
-		Use:   "kube",
+		Use:   "kube [flags] KUBEFILE",
 		Short: "Play a pod based on Kubernetes YAML",
 		Long:  playKubeDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_inspect.go
+++ b/cmd/podman/pod_inspect.go
@ -14,7 +14,7 @@ var (
 	podInspectCommand     cliconfig.PodInspectValues
 	podInspectDescription = "Display the configuration for a pod by name or id"
 	_podInspectCommand    = &cobra.Command{
-		Use:   "inspect",
+		Use:   "inspect [flags] POD",
 		Short: "Displays a pod configuration",
 		Long:  podInspectDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_kill.go
+++ b/cmd/podman/pod_kill.go
@ -16,7 +16,7 @@ var (
 	podKillCommand     cliconfig.PodKillValues
 	podKillDescription = "The main process of each container inside the specified pod will be sent SIGKILL, or any signal specified with option --signal."
 	_podKillCommand    = &cobra.Command{
-		Use:   "kill",
+		Use:   "kill [flags] POD [POD...]",
 		Short: "Send the specified signal or SIGKILL to containers in pod",
 		Long:  podKillDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_pause.go
+++ b/cmd/podman/pod_pause.go
@ -13,7 +13,7 @@ var (
 	podPauseCommand     cliconfig.PodPauseValues
 	podPauseDescription = `Pauses one or more pods.  The pod name or ID can be used.`
 	_podPauseCommand    = &cobra.Command{
-		Use:   "pause",
+		Use:   "pause [flags] POD [POD...]",
 		Short: "Pause one or more pods",
 		Long:  podPauseDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_restart.go
+++ b/cmd/podman/pod_restart.go
@ -14,7 +14,7 @@ var (
 	podRestartCommand     cliconfig.PodRestartValues
 	podRestartDescription = `Restarts one or more pods. The pod ID or name can be used.`
 	_podRestartCommand    = &cobra.Command{
-		Use:   "restart",
+		Use:   "restart [flags] POD [POD...]",
 		Short: "Restart one or more pods",
 		Long:  podRestartDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_rm.go
+++ b/cmd/podman/pod_rm.go
@ -18,7 +18,7 @@ be used.  A pod with containers will not be removed without --force.
 If --force is specified, all containers will be stopped, then removed.
 `)
 	_podRmCommand = &cobra.Command{
-		Use:   "rm",
+		Use:   "rm [flags] POD [POD...]",
 		Short: "Remove one or more pods",
 		Long:  podRmDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_start.go
+++ b/cmd/podman/pod_start.go
@ -18,7 +18,7 @@ var (
   Starts one or more pods.  The pod name or ID can be used.
 `
 	_podStartCommand = &cobra.Command{
-		Use:   "start",
+		Use:   "start POD [POD...]",
 		Short: "Start one or more pods",
 		Long:  podStartDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_stats.go
+++ b/cmd/podman/pod_stats.go
@ -24,7 +24,7 @@ var (
 	podStatsCommand     cliconfig.PodStatsValues
 	podStatsDescription = "Display a live stream of resource usage statistics for the containers in or more pods"
 	_podStatsCommand    = &cobra.Command{
-		Use:   "stats",
+		Use:   "stats [flags] POD [POD...]",
 		Short: "Display percentage of CPU, memory, network I/O, block I/O and PIDs for containers in one or more pods",
 		Long:  podStatsDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_stop.go
+++ b/cmd/podman/pod_stop.go
@ -19,7 +19,7 @@ var (
 `

 	_podStopCommand = &cobra.Command{
-		Use:   "stop",
+		Use:   "stop [flags] POD [POD...]",
 		Short: "Stop one or more pods",
 		Long:  podStopDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_top.go
+++ b/cmd/podman/pod_top.go
@ -25,7 +25,7 @@ the latest pod.
 `, getDescriptorString())

 	_podTopCommand = &cobra.Command{
-		Use:   "top",
+		Use:   "top [flags] CONTAINER [FORMAT-DESCRIPTORS]",
 		Short: "Display the running processes of containers in a pod",
 		Long:  podTopDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pod_unpause.go
+++ b/cmd/podman/pod_unpause.go
@ -14,7 +14,7 @@ var (
 	podUnpauseCommand     cliconfig.PodUnpauseValues
 	podUnpauseDescription = `Unpauses one or more pods.  The pod name or ID can be used.`
 	_podUnpauseCommand    = &cobra.Command{
-		Use:   "unpause",
+		Use:   "unpause [flags] POD [POD...]",
 		Short: "Unpause one or more pods",
 		Long:  podUnpauseDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/port.go
+++ b/cmd/podman/port.go
@ -20,7 +20,7 @@ var (
 	List port mappings for the CONTAINER, or lookup the public-facing port that is NAT-ed to the PRIVATE_PORT
 `
 	_portCommand = &cobra.Command{
-		Use:   "port",
+		Use:   "port [flags] CONTAINER",
 		Short: "List port mappings or a specific mapping for the container",
 		Long:  portDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/pull.go
+++ b/cmd/podman/pull.go
@ -29,7 +29,7 @@ An image can be pulled using its tag or digest. If a tag is not
 specified, the image with the 'latest' tag (if it exists) is pulled
 `
 	_pullCommand = &cobra.Command{
-		Use:   "pull",
+		Use:   "pull [flags] IMAGE-PATH",
 		Short: "Pull an image from a registry",
 		Long:  pullDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/push.go
+++ b/cmd/podman/push.go
@ -26,7 +26,7 @@ var (
   See podman-push(1) section "DESTINATION" for the expected format`)

 	_pushCommand = &cobra.Command{
-		Use:   "push",
+		Use:   "push [flags] IMAGE REGISTRY",
 		Short: "Push an image to a specified destination",
 		Long:  pushDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/restart.go
+++ b/cmd/podman/restart.go
@ -18,7 +18,7 @@ var (
 	restartCommand     cliconfig.RestartValues
 	restartDescription = `Restarts one or more running containers. The container ID or name can be used. A timeout before forcibly stopping can be set, but defaults to 10 seconds`
 	_restartCommand    = &cobra.Command{
-		Use:   "restart",
+		Use:   "restart [flags] CONTAINER [CONTAINER...]",
 		Short: "Restart one or more containers",
 		Long:  restartDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/restore.go
+++ b/cmd/podman/restore.go
@ -21,7 +21,7 @@ var (
   Restores a container from a checkpoint. The container name or ID can be used.
 `
 	_restoreCommand = &cobra.Command{
-		Use:   "restore",
+		Use:   "restore [flags] CONTAINER [CONTAINER...]",
 		Short: "Restores one or more containers from a checkpoint",
 		Long:  restoreDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/rm.go
+++ b/cmd/podman/rm.go
@ -21,7 +21,7 @@ The container name or ID can be used. This does not remove images.
 Running containers will not be removed without the -f option.
 `)
 	_rmCommand = &cobra.Command{
-		Use:   "rm",
+		Use:   "rm [flags] CONTAINER [CONTAINER...]",
 		Short: "Remove one or more containers",
 		Long:  rmDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/rmi.go
+++ b/cmd/podman/rmi.go
@ -17,7 +17,7 @@ var (
 	rmiCommand     cliconfig.RmiValues
 	rmiDescription = "Removes one or more locally stored images."
 	_rmiCommand    = &cobra.Command{
-		Use:   "rmi",
+		Use:   "rmi [flags] IMAGE [IMAGE...]",
 		Short: "Removes one or more images from local storage",
 		Long:  rmiDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/run.go
+++ b/cmd/podman/run.go
@ -23,7 +23,7 @@ var (

 	runDescription = "Runs a command in a new container from the given image"
 	_runCommand    = &cobra.Command{
-		Use:   "run",
+		Use:   "run [flags] IMAGE [COMMAND [ARG...]]",
 		Short: "Run a command in a new container",
 		Long:  runDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/runlabel.go
+++ b/cmd/podman/runlabel.go
@ -22,7 +22,7 @@ var (
 Executes a command as described by a container image label.
 `
 	_runlabelCommand = &cobra.Command{
-		Use:   "runlabel",
+		Use:   "runlabel [flags] LABEL IMAGE [ARG...]",
 		Short: "Execute the command described by an image label",
 		Long:  runlabelDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/save.go
+++ b/cmd/podman/save.go
@ -28,7 +28,7 @@ var (
 	Default is docker-archive`

 	_saveCommand = &cobra.Command{
-		Use:   "save",
+		Use:   "save [flags] IMAGE",
 		Short: "Save image to an archive",
 		Long:  saveDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/search.go
+++ b/cmd/podman/search.go
@ -22,7 +22,7 @@ var (
 	Search registries for a given image. Can search all the default registries or a specific registry.
 	Can limit the number of results, and filter the output based on certain conditions.`
 	_searchCommand = &cobra.Command{
-		Use:   "search",
+		Use:   "search [flags] TERM",
 		Short: "Search registry for image",
 		Long:  searchDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/sign.go
+++ b/cmd/podman/sign.go
@ -24,7 +24,7 @@ var (
 	signCommand     cliconfig.SignValues
 	signDescription = "Create a signature file that can be used later to verify the image"
 	_signCommand    = &cobra.Command{
-		Use:   "sign",
+		Use:   "sign [flags] IMAGE [IMAGE...]",
 		Short: "Sign an image",
 		Long:  signDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/start.go
+++ b/cmd/podman/start.go
@ -21,7 +21,7 @@ var (
   Starts one or more containers.  The container name or ID can be used.
 `
 	_startCommand = &cobra.Command{
-		Use:   "start",
+		Use:   "start [flags] CONTAINER [CONTAINER...]",
 		Short: "Start one or more containers",
 		Long:  startDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/stats.go
+++ b/cmd/podman/stats.go
@ -33,7 +33,7 @@ var (

 	statsDescription = "display a live stream of one or more containers' resource usage statistics"
 	_statsCommand    = &cobra.Command{
-		Use:   "stats",
+		Use:   "stats [flags] CONTAINER [CONTAINER...]",
 		Short: "Display percentage of CPU, memory, network I/O, block I/O and PIDs for one or more containers",
 		Long:  statsDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/stop.go
+++ b/cmd/podman/stop.go
@ -24,7 +24,7 @@ var (
   seconds otherwise.
 `
 	_stopCommand = &cobra.Command{
-		Use:   "stop",
+		Use:   "stop [flags] CONTAINER [CONTAINER...]",
 		Short: "Stop one or more containers",
 		Long:  stopDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/tag.go
+++ b/cmd/podman/tag.go
@ -12,7 +12,7 @@ var (

 	tagDescription = "Adds one or more additional names to locally-stored image"
 	_tagCommand    = &cobra.Command{
-		Use:   "tag",
+		Use:   "tag [flags] IMAGE TAG [TAG...]",
 		Short: "Add an additional name to a local image",
 		Long:  tagDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/top.go
+++ b/cmd/podman/top.go
@ -34,7 +34,7 @@ the latest container.
 `, getDescriptorString())

 	_topCommand = &cobra.Command{
-		Use:   "top",
+		Use:   "top [flags] CONTAINER [FORMAT-DESCRIPTIOS]",
 		Short: "Display the running processes of a container",
 		Long:  topDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/umount.go
+++ b/cmd/podman/umount.go
@ -22,7 +22,7 @@ counter reaches zero indicating no other processes are using the mount.
 An unmount can be forced with the --force flag.
 `
 	_umountCommand = &cobra.Command{
-		Use:     "umount",
+		Use:     "umount [flags] CONTAINER [CONTAINER...]",
 		Aliases: []string{"unmount"},
 		Short:   "Unmounts working container's root filesystem",
 		Long:    description,
--- a/cmd/podman/unpause.go
+++ b/cmd/podman/unpause.go
@ -21,7 +21,7 @@ var (
   Unpauses one or more running containers.  The container name or ID can be used.
 `
 	_unpauseCommand = &cobra.Command{
-		Use:   "unpause",
+		Use:   "unpause [flags] CONTAINER [CONTAINER...]",
 		Short: "Unpause the processes in one or more containers",
 		Long:  unpauseDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/varlink.go
+++ b/cmd/podman/varlink.go
@ -24,7 +24,7 @@ var (
 	run varlink interface
 `
 	_varlinkCommand = &cobra.Command{
-		Use:   "varlink",
+		Use:   "varlink [flags] URI",
 		Short: "Run varlink interface",
 		Long:  varlinkDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/volume_create.go
+++ b/cmd/podman/volume_create.go
@ -18,7 +18,7 @@ Creates a new volume. If using the default driver, "local", the volume will
 be created at.`

 	_volumeCreateCommand = &cobra.Command{
-		Use:   "create",
+		Use:   "create [flags] [NAME]",
 		Short: "Create a new volume",
 		Long:  volumeCreateDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/volume_inspect.go
+++ b/cmd/podman/volume_inspect.go
@ -16,7 +16,7 @@ Display detailed information on one or more volumes. Can change the format
 from JSON to a Go template.
 `
 	_volumeInspectCommand = &cobra.Command{
-		Use:   "inspect",
+		Use:   "inspect [flags] VOLUME [VOLUME...]",
 		Short: "Display detailed information on one or more volumes",
 		Long:  volumeInspectDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/cmd/podman/volume_rm.go
+++ b/cmd/podman/volume_rm.go
@ -19,7 +19,7 @@ not being used by any containers. To remove the volumes anyways, use the
 --force flag.
 `
 	_volumeRmCommand = &cobra.Command{
-		Use:     "rm",
+		Use:     "rm [flags] VOLUME [VOLUME...]",
 		Aliases: []string{"remove"},
 		Short:   "Remove one or more volumes",
 		Long:    volumeRmDescription,
--- a/cmd/podman/wait.go
+++ b/cmd/podman/wait.go
@ -20,7 +20,7 @@ var (
 	Block until one or more containers stop and then print their exit codes
 `
 	_waitCommand = &cobra.Command{
-		Use:   "wait",
+		Use:   "wait [flags] CONTAINER [CONTAINER...]",
 		Short: "Block on one or more containers",
 		Long:  waitDescription,
 		RunE: func(cmd *cobra.Command, args []string) error {
--- a/docs/podman-import.1.md
+++ b/docs/podman-import.1.md
@ -4,13 +4,14 @@
 podman\-import - Import a tarball and save it as a filesystem image

 ## SYNOPSIS
-**podman import** [*options*] *path*
+**podman import** [*options*] *path* [*reference*]

 ## DESCRIPTION
 **podman import** imports a tarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz)
 and saves it as a filesystem image. Remote tarballs can be specified using a URL.
 Various image instructions can be configured with the **--change** flag and
 a commit message can be set using the **--message** flag.
+**reference**, if present, is a tag to assign to the image.
 Note: `:` is a restricted character and cannot be part of the file name.

 ## OPTIONS