docs: pass on sub-command help

cli/app/app.go

@@ -5,11 +5,10 @@ import (
 )
 
 var AppCommand = cli.Command{
-	Name:        "app",
-	Aliases:     []string{"a"},
-	Usage:       "Manage apps",
-	ArgsUsage:   "<domain>",
-	Description: "Functionality for managing the life cycle of your apps",
+	Name:      "app",
+	Aliases:   []string{"a"},
+	Usage:     "Manage apps",
+	ArgsUsage: "<domain>",
 	Subcommands: []cli.Command{
 		appBackupCommand,
 		appCheckCommand,

cli/app/cmd.go

@@ -29,10 +29,11 @@ They can be run within the context of a service (e.g. app) or locally on your
 work station by passing "--local". Arguments can be passed into these functions
 using the "-- <args>" syntax.
 
-Example:
+**WARNING**: options must be passed directly after the sub-command "cmd".
 
-  abra app cmd example.com app create_user -- me@example.com
-`,
+EXAMPLE:
+
+  abra app cmd --local example.com app create_user -- me@example.com`,
 	ArgsUsage: "<domain> [<service>] <command> [-- <args>]",
 	Flags: []cli.Flag{
 		internal.DebugFlag,

cli/app/config.go

@@ -43,7 +43,7 @@ var appConfigCommand = cli.Command{
 		ed, ok := os.LookupEnv("EDITOR")
 		if !ok {
 			edPrompt := &survey.Select{
-				Message: "Which editor do you wish to use?",
+				Message: "which editor do you wish to use?",
 				Options: []string{"vi", "vim", "nvim", "nano", "pico", "emacs"},
 			}
 			if err := survey.AskOne(edPrompt, &ed); err != nil {

cli/app/deploy.go

@@ -35,17 +35,12 @@ var appDeployCommand = cli.Command{
 		internal.OfflineFlag,
 	},
 	Before: internal.SubCommandBefore,
-	Description: `
-Deploy an app. It does not support incrementing the version of a deployed app,
-for this you need to look at the "abra app upgrade <domain>" command.
+	Description: `Deploy an app.
 
-You may pass "--force" to re-deploy the same version again. This can be useful
-if the container runtime has gotten into a weird state.
+Use "--force" to re-deploy the same version again.
 
-Chaos mode ("--chaos") will deploy your local checkout of a recipe as-is,
-including unstaged changes and can be useful for live hacking and testing new
-recipes.
-`,
+Use "--chaos"  to deploy your local checkout of a recipe as-is, including
+unstaged changes.`,
 	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)

cli/app/list.go

@@ -77,8 +77,7 @@ generate a report of all your apps.
 
 By passing the "--status/-S" flag, you can query all your servers for the
 actual live deployment status. Depending on how many servers you manage, this
-can take some time.
-`,
+can take some time.`,
 	Flags: []cli.Flag{
 		internal.DebugFlag,
 		internal.MachineReadableFlag,

cli/app/new.go

@@ -19,8 +19,8 @@ import (
 )
 
 var appNewDescription = `
-Take a recipe and uses it to create a new app. This new app configuration is
-stored in your ~/.abra directory under the appropriate server.
+Creates a new app from a default recipe. This new app configuration is stored
+in your $ABRA_DIR directory under the appropriate server.
 
 This command does not deploy your app for you. You will need to run "abra app
 deploy <domain>" to do so.
@@ -35,8 +35,7 @@ store them somewhere safe.
 
 You can use the "--pass/-P" to store these generated passwords locally in a
 pass store (see passwordstore.org for more). The pass command must be available
-on your $PATH.
-`
+on your $PATH.`
 
 var appNewCommand = cli.Command{
 	Name:        "new",
@@ -174,22 +173,25 @@ var appNewCommand = cli.Command{
 		table := formatter.CreateTable(tableCol)
 		table.Append([]string{internal.NewAppServer, recipe.Name, internal.Domain})
 
-		fmt.Println(fmt.Sprintf("A new %s app has been created! Here is an overview:", recipe.Name))
+		log.Infof("new app '%s' created 🌞", recipe.Name)
+
 		fmt.Println("")
 		table.Render()
 		fmt.Println("")
-		fmt.Println("You can configure this app by running the following:")
+
+		fmt.Println("Configure this app:")
 		fmt.Println(fmt.Sprintf("\n    abra app config %s", internal.Domain))
+
 		fmt.Println("")
-		fmt.Println("You can deploy this app by running the following:")
+		fmt.Println("Deploy this app:")
 		fmt.Println(fmt.Sprintf("\n    abra app deploy %s", internal.Domain))
 
 		if len(secrets) > 0 {
 			fmt.Println("")
-			fmt.Println("Here are your generated secrets:")
+			fmt.Println("Generated secrets:")
 			fmt.Println("")
 			secretTable.Render()
-			log.Warn("generated secrets are not shown again, please take note of them NOW")
+			log.Warn("Generated secrets are not shown again, please take note of them NOW")
 		}
 
 		return nil

cli/app/remove.go

@@ -36,8 +36,7 @@ Please note, if you delete the local app env file without removing volumes and
 secrets first, Abra will *not* be able to help you remove them afterwards.
 
 To delete everything without prompt, use the "--force/-f" or the "--no-input/n"
-flag.
-`,
+flag.`,
 	Flags: []cli.Flag{
 		internal.ForceFlag,
 		internal.DebugFlag,

cli/app/restart.go

@@ -33,10 +33,9 @@ Run "abra app ps <domain>" to see a list of service names.
 
 Pass "--all-services/-a" to restart all services.
 
-Example:
+EXAMPLE:
 
-    abra app restart example.com app
-`,
+    abra app restart example.com app`,
 	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)

cli/app/rollback.go

@@ -34,14 +34,13 @@ var appRollbackCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-This command rolls an app back to a previous version if one exists.
+This command rolls an app back to a previous version.
 
 You may pass "--force/-f" to downgrade to the same version again. This can be
 useful if the container runtime has gotten into a weird state.
 
 This action could be destructive, please ensure you have a copy of your app
-data beforehand.
-`,
+data beforehand.`,
 	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)

cli/app/undeploy.go

@@ -78,8 +78,7 @@ This does not destroy any of the application data.
 However, you should remain vigilant, as your swarm installation will consider
 any previously attached volumes as eligible for pruning once undeployed.
 
-Passing "-p/--prune" does not remove those volumes.
-`,
+Passing "-p/--prune" does not remove those volumes.`,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 		stackName := app.StackName()

cli/app/upgrade.go

@@ -34,15 +34,10 @@ var appUpgradeCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-Upgrade an app. You can use it to choose and roll out a new upgrade to a
-deployed app.
-
-You may pass "--force/-f" to upgrade to the same version again. This can be
-useful if the container runtime has gotten into a weird state.
+Upgrade an app.
 
 This action could be destructive, please ensure you have a copy of your app
-data beforehand.
-`,
+data beforehand.`,
 	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)

cli/app/volume.go

@@ -73,8 +73,7 @@ The command is interactive and will show a multiple select input which allows
 you to make a seclection. Use the "?" key to see more help on navigating this
 interface.
 
-Passing "--force/-f" will select all volumes for removal. Be careful.
-`,
+Passing "--force/-f" will select all volumes for removal. Be careful.`,
 	ArgsUsage: "<domain>",
 	Aliases:   []string{"rm"},
 	Flags: []cli.Flag{