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>

58 files changed, 65 insertions, 61 deletions

diff --git a/cmd/podman/attach.go b/cmd/podman/attach.go
index 074675e45..a22aa92a1 100644
--- 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 {
diff --git a/cmd/podman/build.go b/cmd/podman/build.go
index e40e35cb5..8ea9e6957 100644
--- 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 {
diff --git a/cmd/podman/checkpoint.go b/cmd/podman/checkpoint.go
index c9de5638b..8c4b8ad3c 100644
--- 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 {
diff --git a/cmd/podman/cleanup.go b/cmd/podman/cleanup.go
index 33d456643..fbbd337a7 100644
--- 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 {
diff --git a/cmd/podman/commit.go b/cmd/podman/commit.go
index d8ced0e36..43c54c320 100644
--- 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 {
diff --git a/cmd/podman/cp.go b/cmd/podman/cp.go
index d9f230b67..30b6d75d2 100644
--- 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 {
diff --git a/cmd/podman/create.go b/cmd/podman/create.go
index 868f90d54..2d93c149a 100644
--- 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 {
diff --git a/cmd/podman/diff.go b/cmd/podman/diff.go
index e2d258ad4..e232d7e66 100644
--- 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 {
diff --git a/cmd/podman/exec.go b/cmd/podman/exec.go
index 7040a7b09..032262497 100644
--- 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 {
diff --git a/cmd/podman/exists.go b/cmd/podman/exists.go
index 74a4c841b..c01a6a081 100644
--- 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())
 }
 
diff --git a/cmd/podman/export.go b/cmd/podman/export.go
index 5873bad3d..d40c05019 100644
--- 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 {
diff --git a/cmd/podman/generate_kube.go b/cmd/podman/generate_kube.go
index 15f374c73..090f99495 100644
--- 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 {
diff --git a/cmd/podman/history.go b/cmd/podman/history.go
index 103ef08e8..533ee91cb 100644
--- 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 {
diff --git a/cmd/podman/import.go b/cmd/podman/import.go
index a64b03d6d..ddf1bd802 100644
--- 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 {
diff --git a/cmd/podman/inspect.go b/cmd/podman/inspect.go
index 46883b31d..1c93a03e1 100644
--- 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 {
diff --git a/cmd/podman/kill.go b/cmd/podman/kill.go
index eb72d53e7..76d2516b7 100644
--- 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 {
diff --git a/cmd/podman/load.go b/cmd/podman/load.go
index 272cd78d2..5a0742aba 100644
--- 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 {
diff --git a/cmd/podman/login.go b/cmd/podman/login.go
index b02a4b3f9..48d4eefbc 100644
--- 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 {
diff --git a/cmd/podman/logout.go b/cmd/podman/logout.go
index 4108887f0..2a540ceba 100644
--- 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 {
diff --git a/cmd/podman/logs.go b/cmd/podman/logs.go
index 40ae2c846..a02010eda 100644
--- 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 {
diff --git a/cmd/podman/mount.go b/cmd/podman/mount.go
index f4a7bd5ea..3a3432194 100644
--- 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 {
diff --git a/cmd/podman/pause.go b/cmd/podman/pause.go
index 94bb0edfe..3a5b80359 100644
--- 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`,
 	}
 )
 
diff --git a/cmd/podman/play_kube.go b/cmd/podman/play_kube.go
index 1a45cbed9..6f23e340e 100644
--- 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 {
diff --git a/cmd/podman/pod_inspect.go b/cmd/podman/pod_inspect.go
index 5a32b5c5d..8b2747af0 100644
--- 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 {
diff --git a/cmd/podman/pod_kill.go b/cmd/podman/pod_kill.go
index aaaae0f7d..70d86d186 100644
--- 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 {
diff --git a/cmd/podman/pod_pause.go b/cmd/podman/pod_pause.go
index 284740d22..f7c90dbbe 100644
--- 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 {
diff --git a/cmd/podman/pod_restart.go b/cmd/podman/pod_restart.go
index 741fce588..ba77e1409 100644
--- 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 {
diff --git a/cmd/podman/pod_rm.go b/cmd/podman/pod_rm.go
index ba16d03c7..fa452b061 100644
--- 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 {
diff --git a/cmd/podman/pod_start.go b/cmd/podman/pod_start.go
index 5761afd52..eef9d2a71 100644
--- 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 {
diff --git a/cmd/podman/pod_stats.go b/cmd/podman/pod_stats.go
index 907d6a547..f5edd21f8 100644
--- 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 {
diff --git a/cmd/podman/pod_stop.go b/cmd/podman/pod_stop.go
index 62d0d4aa5..951cf082a 100644
--- 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 {
diff --git a/cmd/podman/pod_top.go b/cmd/podman/pod_top.go
index 790118496..6a26e3dff 100644
--- 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 {
diff --git a/cmd/podman/pod_unpause.go b/cmd/podman/pod_unpause.go
index 16481d0e2..6b142d573 100644
--- 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 {
diff --git a/cmd/podman/port.go b/cmd/podman/port.go
index bcf372a51..1c3086536 100644
--- 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 {
diff --git a/cmd/podman/pull.go b/cmd/podman/pull.go
index 71f555162..5f4658fe1 100644
--- 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 {
diff --git a/cmd/podman/push.go b/cmd/podman/push.go
index 56261a8d3..bc909cb5e 100644
--- 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 {
diff --git a/cmd/podman/restart.go b/cmd/podman/restart.go
index 58fb38874..2bebde4f9 100644
--- 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 {
diff --git a/cmd/podman/restore.go b/cmd/podman/restore.go
index 5f6e7b892..73d355734 100644
--- 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 {
diff --git a/cmd/podman/rm.go b/cmd/podman/rm.go
index 2dcb491d7..61b049840 100644
--- 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 {
diff --git a/cmd/podman/rmi.go b/cmd/podman/rmi.go
index 709ed14e0..0963b1328 100644
--- 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 {
diff --git a/cmd/podman/run.go b/cmd/podman/run.go
index bea9b1743..f66b939d3 100644
--- 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 {
diff --git a/cmd/podman/runlabel.go b/cmd/podman/runlabel.go
index d466651f3..bc4e650f9 100644
--- 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 {
diff --git a/cmd/podman/save.go b/cmd/podman/save.go
index 161540deb..3bc283772 100644
--- 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 {
diff --git a/cmd/podman/search.go b/cmd/podman/search.go
index f63131c84..5c14f1ff1 100644
--- 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 {
diff --git a/cmd/podman/sign.go b/cmd/podman/sign.go
index 6e8f9ee95..2cf228d01 100644
--- 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 {
diff --git a/cmd/podman/start.go b/cmd/podman/start.go
index c645a35c4..3ce04ea79 100644
--- 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 {
diff --git a/cmd/podman/stats.go b/cmd/podman/stats.go
index 2bbcd0a17..dcb274471 100644
--- 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 {
diff --git a/cmd/podman/stop.go b/cmd/podman/stop.go
index 67c15b2a8..d86894a6f 100644
--- 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 {
diff --git a/cmd/podman/tag.go b/cmd/podman/tag.go
index 2b9d67066..98c6e3449 100644
--- 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 {
diff --git a/cmd/podman/top.go b/cmd/podman/top.go
index 36d6bb6b4..cdf270fa7 100644
--- 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 {
diff --git a/cmd/podman/umount.go b/cmd/podman/umount.go
index 6d9009388..48c97fa31 100644
--- 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,
diff --git a/cmd/podman/unpause.go b/cmd/podman/unpause.go
index efd9a20a3..58fd19fe1 100644
--- 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 {
diff --git a/cmd/podman/varlink.go b/cmd/podman/varlink.go
index d9c6cdb47..f19d03885 100644
--- 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 {
diff --git a/cmd/podman/volume_create.go b/cmd/podman/volume_create.go
index 833191082..96b2ed8c7 100644
--- 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 {
diff --git a/cmd/podman/volume_inspect.go b/cmd/podman/volume_inspect.go
index dc6afbc36..8add7a375 100644
--- 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 {
diff --git a/cmd/podman/volume_rm.go b/cmd/podman/volume_rm.go
index 03b6ccae1..73b1a6668 100644
--- 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,
diff --git a/cmd/podman/wait.go b/cmd/podman/wait.go
index 9df7cdbae..9df2e3208 100644
--- 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 {
diff --git a/docs/podman-import.1.md b/docs/podman-import.1.md
index c80c4ff77..03055018a 100644
--- 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