Merge pull request #85 from mnottale/cli-help

cli: improve help messages.

Author: mnottale

cmd/deploy.go

@@ -3,15 +3,20 @@ package cmd
 import (
 	"fmt"
 
+	"github.com/docker/cli/cli"
 	"github.com/docker/lunchbox/internal"
 	"github.com/docker/lunchbox/renderer"
 	"github.com/spf13/cobra"
 )
 
 // deployCmd represents the deploy command
 var deployCmd = &cobra.Command{
-	Use:   "deploy <app-name>",
+	Use:   "deploy [<app-name>]",
 	Short: "Deploy the specified app on the connected cluster",
+	Long: `Deploy the application on either swarm or kubernetes.
+The app's docker-compose.yml is first rendered as per the render sub-command, and
+then deployed similarly to 'docker stack deploy'.`,
+	Args: cli.RequiresMaxArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if deployOrchestrator != "swarm" && deployOrchestrator != "kubernetes" {
 			return fmt.Errorf("orchestrator must be either 'swarm' or 'kubernetes'")

cmd/helm.go

@@ -8,9 +8,17 @@ import (
 )
 
 var helmCmd = &cobra.Command{
-	Use:   "helm <app-name> [-c <compose-files>...] [-e key=value...] [-f settings-file...]",
+	Use:   "helm [<app-name>] [-s key=value...] [-f settings-file...]",
 	Short: "Render the Compose file for this app as an Helm package",
-	Args:  cli.RequiresMaxArgs(1),
+	Long: `The helm command creates or updates the directory <app-name>.chart.
+- Chart.yaml is created or updated from the app's metadata.
+- values.yaml is created or updated with the values from settings which are
+  actually used by the compose file.
+- templates/stack.yaml is created, with a stack template extracted from the app's
+docker-compose.yml. If the --render option is used, the docker-compose.yml will
+be rendered instead of exported as a template. Note that template export will
+not work if you use go templating, only variable substitution is supported.`,
+	Args: cli.RequiresMaxArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		d, err := parseSettings(helmEnv)
 		if err != nil {
@@ -29,6 +37,7 @@ func init() {
 	rootCmd.AddCommand(helmCmd)
 	if internal.Experimental == "on" {
 		helmCmd.Flags().StringArrayVarP(&helmComposeFiles, "compose-files", "c", []string{}, "Override Compose files")
+		helmCmd.Use += " [-c <compose-files>...]"
 	}
 	helmCmd.Flags().StringArrayVarP(&helmSettingsFile, "settings-files", "f", []string{}, "Override settings files")
 	helmCmd.Flags().StringArrayVarP(&helmEnv, "set", "s", []string{}, "Override environment values")

cmd/image-add.go

@@ -12,7 +12,10 @@ import (
 var imageAddCmd = &cobra.Command{
 	Use:   "image-add <app-name> [services...]",
 	Short: "Add images for given services (default: all) to the app package",
-	Args:  cobra.MinimumNArgs(1),
+	Long: `This command renders the app's docker-compose.yml file, looks for the
+images it uses, and saves them from the local docker daemon to the images/
+subdirectory.`,
+	Args: cobra.MinimumNArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		d := make(map[string]string)
 		for _, v := range imageAddEnv {

cmd/init.go

@@ -10,7 +10,10 @@ import (
 var initCmd = &cobra.Command{
 	Use:   "init <app-name> [-c <compose-file>]",
 	Short: "Initialize an app package in the current working directory",
-	Args:  cli.ExactArgs(1),
+	Long: `This command initializes a new app package. If the -c option is used, or
+if a file named docker-compose.yml is found in the current directory, this file
+and the associated .env file if found will be used as the base for this application.`,
+	Args: cli.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return packager.Init(args[0], composeFile)
 	},

cmd/inspect.go

@@ -8,8 +8,8 @@ import (
 
 // inspectCmd represents the inspect command
 var inspectCmd = &cobra.Command{
-	Use:   "inspect <app-name>",
-	Short: "Retrieve metadata for a given app package",
+	Use:   "inspect [<app-name>]",
+	Short: "Shows metadata and settings for a given app package",
 	Args:  cli.RequiresMaxArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return renderer.Inspect(firstOrEmpty(args))

cmd/pack.go

@@ -8,7 +8,7 @@ import (
 )
 
 var packCmd = &cobra.Command{
-	Use:   "pack <app-name> [-o output_file]",
+	Use:   "pack [<app-name>] [-o output_file]",
 	Short: "Pack this app as a single file",
 	Args:  cli.RequiresMaxArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {

cmd/push.go

@@ -8,7 +8,7 @@ import (
 )
 
 var pushCmd = &cobra.Command{
-	Use:   "push <app-name>",
+	Use:   "push [<app-name>]",
 	Short: "Push the application to a registry",
 	Args:  cli.RequiresMaxArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {

cmd/root.go

@@ -12,9 +12,12 @@ import (
 
 // rootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
-	Use:          "docker-app",
-	Short:        "Docker App Packages",
-	Long:         "",
+	Use:   "docker-app",
+	Short: "Docker App Packages",
+	Long: `Create, render deploy and otherwise manipulate an app package.
+For most sub-commands that take an app-package as only positional argument, this
+argument is optional: an app package is looked for in the current working directory.
+All commands accept both compressed and uncompressed app packages.`,
 	SilenceUsage: true,
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 		if internal.Debug {

cmd/save.go

@@ -8,8 +8,8 @@ import (
 )
 
 var saveCmd = &cobra.Command{
-	Use:   "save <app-name>",
-	Short: "Save the application to docker (in preparation for push)",
+	Use:   "save [<app-name>]",
+	Short: "Save the application as an image to the docker daemon(in preparation for push)",
 	Args:  cli.RequiresMaxArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if saveTag == "" {