Rework command help and flags

- Align usage with Docker CLI
- Remove short options that are not commonly used
- Clarify help and flag messages
- Add examples for each command

Signed-off-by: Christopher Crone <[email protected]>

Author: chris-crone

e2e/plugin_test.go

@@ -15,7 +15,7 @@ func TestInvokePluginFromCLI(t *testing.T) {
 	// docker --help should list app as a top command
 	cmd.Command = dockerCli.Command("--help")
 	icmd.RunCmd(cmd).Assert(t, icmd.Expected{
-		Out: "app*        Docker Application Packages (Docker Inc.,",
+		Out: "app*        Docker Application (Docker Inc.,",
 	})
 
 	// docker app --help prints docker-app help
@@ -30,7 +30,7 @@ func TestInvokePluginFromCLI(t *testing.T) {
 
 	// docker info should print app version and short description
 	cmd.Command = dockerCli.Command("info")
-	re := regexp.MustCompile(`app: Docker Application Packages \(Docker Inc\., .*\)`)
+	re := regexp.MustCompile(`app: Docker Application \(Docker Inc\., .*\)`)
 	output := icmd.RunCmd(cmd).Assert(t, icmd.Success).Combined()
 	assert.Assert(t, re.MatchString(output))
 }

e2e/testdata/plugin-usage-experimental.golden

@@ -1,20 +1,20 @@
 
 Usage:	docker app COMMAND
 
-Build and deploy Docker Application Packages.
+A tool to build and manage Docker Applications.
 
 Commands:
-  bundle      Create a CNAB invocation image and bundle.json for the application
+  bundle      Create a CNAB invocation image and `bundle.json` for the application
   completion  Generates completion scripts for the specified shell (bash or zsh)
-  init        Start building a Docker application
-  inspect     Shows metadata, parameters and a summary of the compose file for a given application
+  init        Initialize Docker Application definition
+  inspect     Shows metadata, parameters and a summary of the Compose file for a given application
   install     Install an application
-  merge       Merge a multi-file application into a single file
-  pull        Pull an application from a registry
-  push        Push the application to a registry
-  render      Render the Compose file for the application
-  split       Split a single-file application into multiple files
-  status      Get the installation status. If the installation is a docker application, the status shows the stack services.
+  merge       Merge a directory format Docker Application definition into a single file
+  pull        Pull an application package from a registry
+  push        Push an application package to a registry
+  render      Render the Compose file for an Application Package
+  split       Split a single-file Docker Application definition into the directory format
+  status      Get the installation status of an application
   uninstall   Uninstall an application
   upgrade     Upgrade an installed application
   validate    Checks the rendered application is syntactically correct

e2e/testdata/plugin-usage.golden

@@ -1,20 +1,20 @@
 
 Usage:	docker app COMMAND
 
-Build and deploy Docker Application Packages.
+A tool to build and manage Docker Applications.
 
 Commands:
-  bundle      Create a CNAB invocation image and bundle.json for the application
+  bundle      Create a CNAB invocation image and `bundle.json` for the application
   completion  Generates completion scripts for the specified shell (bash or zsh)
-  init        Start building a Docker application
-  inspect     Shows metadata, parameters and a summary of the compose file for a given application
+  init        Initialize Docker Application definition
+  inspect     Shows metadata, parameters and a summary of the Compose file for a given application
   install     Install an application
-  merge       Merge a multi-file application into a single file
-  pull        Pull an application from a registry
-  push        Push the application to a registry
-  render      Render the Compose file for the application
-  split       Split a single-file application into multiple files
-  status      Get the installation status. If the installation is a docker application, the status shows the stack services.
+  merge       Merge a directory format Docker Application definition into a single file
+  pull        Pull an application package from a registry
+  push        Push an application package to a registry
+  render      Render the Compose file for an Application Package
+  split       Split a single-file Docker Application definition into the directory format
+  status      Get the installation status of an application
   uninstall   Uninstall an application
   upgrade     Upgrade an installed application
   validate    Checks the rendered application is syntactically correct

internal/commands/bundle.go

@@ -28,15 +28,16 @@ type bundleOptions struct {
 func bundleCmd(dockerCli command.Cli) *cobra.Command {
 	var opts bundleOptions
 	cmd := &cobra.Command{
-		Use:   "bundle [<app-name>]",
-		Short: "Create a CNAB invocation image and bundle.json for the application",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "bundle [APP_NAME] [--output OUTPUT_FILE]",
+		Short:   "Create a CNAB invocation image and `bundle.json` for the application",
+		Example: `$ docker app bundle myapp.dockerapp`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runBundle(dockerCli, firstOrEmpty(args), opts)
 		},
 	}
 
-	cmd.Flags().StringVarP(&opts.out, "output", "o", "bundle.json", "path to the output bundle.json (- for stdout)")
+	cmd.Flags().StringVarP(&opts.out, "output", "o", "bundle.json", "Output file (- for stdout)")
 	return cmd
 }
 

internal/commands/completion.go

@@ -14,19 +14,20 @@ func completionCmd(dockerCli command.Cli, rootCmd *cobra.Command) *cobra.Command
 	return &cobra.Command{
 		Use:   "completion SHELL",
 		Short: "Generates completion scripts for the specified shell (bash or zsh)",
-		Long: `# Load the docker-app completion code for bash into the current shell
-. <(docker-app completion bash)
-# Set the docker-app completion code for bash to autoload on startup in your ~/.bashrc,
+		Long: `# Load the "docker app" completion code for bash into the current shell
+. <(docker app completion bash)
+# Set the "docker app" completion code for bash to autoload on startup in your ~/.bashrc,
 # ~/.profile or ~/.bash_profile
-. <(docker-app completion bash)
+. <(docker app completion bash)
 # Note: bash-completion is needed.
 
-# Load the docker-app completion code for zsh into the current shell
-source <(docker-app completion zsh)
-# Set the docker-app completion code for zsh to autoload on startup in your ~/.zshrc
-source <(docker-app completion zsh)
+# Load the "docker app" completion code for zsh into the current shell
+source <(docker app completion zsh)
+# Set the "docker app" completion code for zsh to autoload on startup in your ~/.zshrc,
+source <(docker app completion zsh)
 `,
-		Args: cli.RequiresMaxArgs(1),
+		Example: `$ . <(docker app completion bash)`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			switch {
 			case len(args) == 0:

internal/commands/init.go

@@ -15,17 +15,18 @@ var (
 
 func initCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "init <app-name> [-c <compose-file>] [-d <description>] [-m name:email ...]",
-		Short: "Start building a Docker application",
-		Long:  `Start building a Docker application. Will automatically detect a docker-compose.yml file in the current directory.`,
-		Args:  cli.ExactArgs(1),
+		Use:     "init APP_NAME [--compose-file COMPOSE_FILE] [--description DESCRIPTION] [--maintainer NAME:EMAIL ...] [OPTIONS]",
+		Short:   "Initialize Docker Application definition",
+		Long:    `Start building a Docker Application package. If there is a docker-compose.yml file in the current directory it will be copied and used.`,
+		Example: `$ docker app init myapp --description "a useful description"`,
+		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return packager.Init(args[0], initComposeFile, initDescription, initMaintainers, initSingleFile)
 		},
 	}
-	cmd.Flags().StringVarP(&initComposeFile, "compose-file", "c", "", "Initial Compose file (optional)")
-	cmd.Flags().StringVarP(&initDescription, "description", "d", "", "Initial description (optional)")
-	cmd.Flags().StringArrayVarP(&initMaintainers, "maintainer", "m", []string{}, "Maintainer (name:email) (optional)")
-	cmd.Flags().BoolVarP(&initSingleFile, "single-file", "s", false, "Create a single-file application")
+	cmd.Flags().StringVar(&initComposeFile, "compose-file", "", "Compose file to use as application base (optional)")
+	cmd.Flags().StringVar(&initDescription, "description", "", "Human readable description of your application (optional)")
+	cmd.Flags().StringArrayVar(&initMaintainers, "maintainer", []string{}, "Name and email address of person responsible for the application (name:email) (optional)")
+	cmd.Flags().BoolVar(&initSingleFile, "single-file", false, "Create a single-file Docker Application definition")
 	return cmd
 }

internal/commands/inspect.go

@@ -18,9 +18,10 @@ type inspectOptions struct {
 func inspectCmd(dockerCli command.Cli) *cobra.Command {
 	var opts inspectOptions
 	cmd := &cobra.Command{
-		Use:   "inspect [<app-name>] [-s key=value...] [-f parameters-file...]",
-		Short: "Shows metadata, parameters and a summary of the compose file for a given application",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "inspect [APP_NAME] [OPTIONS]",
+		Short:   "Shows metadata, parameters and a summary of the Compose file for a given application",
+		Example: `$ docker app inspect myapp.dockerapp`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runInspect(dockerCli, firstOrEmpty(args), opts)
 		},

internal/commands/install.go

@@ -31,22 +31,25 @@ const (
 	nameKindReference
 )
 
-const longDescription = `Install the application on either Swarm or Kubernetes.
-Bundle name is optional, and can:
-- be empty and resolve to any *.dockerapp in working directory
-- be a BUNDLE file path and resolve to any *.dockerapp file or dir, or any CNAB file (signed or unsigned)
-- match a bundle name in the local bundle repository
-- refer to a CNAB in a container registry
-`
+const longDescription = `Install an application.
+By default, the application definition in the current directory will be
+installed. The APP_NAME can also be:
+- a path to a Docker Application definition (.dockerapp) or a CNAB bundle.json
+- a registry Application Package reference`
+
+const example = `$ docker app install myapp.dockerapp --name myinstallation --target-context=mycontext
+$ docker app install myrepo/myapp:mytag --name myinstallation --target-context=mycontext
+$ docker app install bundle.json --name myinstallation --credential-set=mycredentials.yml`
 
 func installCmd(dockerCli command.Cli) *cobra.Command {
 	var opts installOptions
 
 	cmd := &cobra.Command{
-		Use:     "install [<bundle name>] [OPTIONS]",
+		Use:     "install [APP_NAME] [--name INSTALLATION_NAME] [--target-context TARGET_CONTEXT] [OPTIONS]",
 		Aliases: []string{"deploy"},
 		Short:   "Install an application",
 		Long:    longDescription,
+		Example: example,
 		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runInstall(dockerCli, firstOrEmpty(args), opts)
@@ -56,7 +59,7 @@ func installCmd(dockerCli command.Cli) *cobra.Command {
 	opts.credentialOptions.addFlags(cmd.Flags())
 	opts.registryOptions.addFlags(cmd.Flags())
 	opts.pullOptions.addFlags(cmd.Flags())
-	cmd.Flags().StringVarP(&opts.orchestrator, "orchestrator", "o", "", "Orchestrator to install on (swarm, kubernetes)")
+	cmd.Flags().StringVar(&opts.orchestrator, "orchestrator", "", "Orchestrator to install on (swarm, kubernetes)")
 	cmd.Flags().StringVar(&opts.kubeNamespace, "kubernetes-namespace", "default", "Kubernetes namespace to install into")
 	cmd.Flags().StringVar(&opts.stackName, "name", "", "Installation name (defaults to application name)")
 

internal/commands/merge.go

@@ -61,9 +61,10 @@ func removeAndRename(source, target string) error {
 
 func mergeCmd(dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "merge [<app-name>] [-o output_file]",
-		Short: "Merge a multi-file application into a single file",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "merge [APP_NAME] [--output OUTPUT_FILE]",
+		Short:   "Merge a directory format Docker Application definition into a single file",
+		Example: `$ docker app merge myapp.dockerapp --output myapp-single.dockerapp`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			extractedApp, err := packager.Extract(firstOrEmpty(args))
 			if err != nil {

internal/commands/pull.go

@@ -15,9 +15,10 @@ import (
 func pullCmd(dockerCli command.Cli) *cobra.Command {
 	var opts registryOptions
 	cmd := &cobra.Command{
-		Use:   "pull <repotag>",
-		Short: "Pull an application from a registry",
-		Args:  cli.ExactArgs(1),
+		Use:     "pull NAME:TAG [OPTIONS]",
+		Short:   "Pull an application package from a registry",
+		Example: `$ docker app pull docker/app-example:0.1.0`,
+		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runPull(dockerCli, args[0], opts)
 		},