docs: pass on sub-command help

cli/app/app.go

@@ -5,11 +5,10 @@ import (
 )
 
 var AppCommand = cli.Command{
-	Name:        "app",
+	Name:      "app",
-	Aliases:     []string{"a"},
+	Aliases:   []string{"a"},
-	Usage:       "Manage apps",
+	Usage:     "Manage apps",
-	ArgsUsage:   "<domain>",
+	ArgsUsage: "<domain>",
-	Description: "Functionality for managing the life cycle of your apps",
 	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: `
+	Description: `Deploy an app.
-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.
 
-You may pass "--force" to re-deploy the same version again. This can be useful
+Use "--force" to re-deploy the same version again.
-if the container runtime has gotten into a weird state.
 
-Chaos mode ("--chaos") will deploy your local checkout of a recipe as-is,
+Use "--chaos"  to deploy your local checkout of a recipe as-is, including
-including unstaged changes and can be useful for live hacking and testing new
+unstaged changes.`,
-recipes.
-`,
 	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
+Creates a new app from a default recipe. This new app configuration is stored
-stored in your ~/.abra directory under the appropriate server.
+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
+Upgrade an app.
-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.
 
 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{

cli/catalogue/catalogue.go

@@ -33,14 +33,7 @@ var catalogueGenerateCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-Generate a new copy of the recipe catalogue which can be found on:
+Generate a new copy of the recipe catalogue.
-
-    https://recipes.coopcloud.tech (website that humans read)
-    https://recipes.coopcloud.tech/recipes.json (JSON that Abra reads)
-
-It polls the entire git.coopcloud.tech/coop-cloud/... recipe repository
-listing, parses README.md and git tags to produce recipe metadata which is
-loaded into the catalogue JSON file.
 
 It is possible to generate new metadata for a single recipe by passing
 <recipe>. The existing local catalogue will be updated, not overwritten.
@@ -51,8 +44,7 @@ If you have a Hub account you can have Abra log you in to avoid this. Pass
 
 Push your new release to git.coopcloud.tech with "-p/--publish". This requires
 that you have permission to git push to these repositories and have your SSH
-keys configured on your account.
+keys configured on your account.`,
-`,
 	ArgsUsage:    "[<recipe>]",
 	BashComplete: autocomplete.RecipeNameComplete,
 	Action: func(c *cli.Context) error {
@@ -213,11 +205,10 @@ keys configured on your account.
 
 // CatalogueCommand defines the `abra catalogue` command and sub-commands.
 var CatalogueCommand = cli.Command{
-	Name:        "catalogue",
+	Name:      "catalogue",
-	Usage:       "Manage the recipe catalogue",
+	Usage:     "Manage the recipe catalogue",
-	Aliases:     []string{"c"},
+	Aliases:   []string{"c"},
-	ArgsUsage:   "<recipe>",
+	ArgsUsage: "<recipe>",
-	Description: "This command helps recipe packagers interact with the recipe catalogue",
 	Subcommands: []cli.Command{
 		catalogueGenerateCommand,
 	},

cli/cli.go

@@ -25,16 +25,15 @@ import (
 var AutoCompleteCommand = cli.Command{
 	Name:    "autocomplete",
 	Aliases: []string{"ac"},
-	Usage:   "Configure shell autocompletion (recommended)",
+	Usage:   "Configure shell autocompletion",
 	Description: `
-Set up auto-completion in your shell by downloading the relevant files and
+Set up shell auto-completion.
-laying out what additional information must be loaded. Supported shells are as
-follows: bash, fish, fizsh & zsh.
 
-Example:
+Supported shells are: bash, fish, fizsh & zsh.
 
-    abra autocomplete bash
+EXAMPLE:
-`,
+
+    abra autocomplete bash`,
 	ArgsUsage: "<shell>",
 	Flags: []cli.Flag{
 		internal.DebugFlag,
@@ -81,7 +80,7 @@ Example:
 		switch shellType {
 		case "bash":
 			fmt.Println(fmt.Sprintf(`
-# Run the following commands to install auto-completion
+# run the following commands to install auto-completion
 sudo mkdir /etc/bash_completion.d/
 sudo cp %s /etc/bash_completion.d/abra
 echo "source /etc/bash_completion.d/abra" >> ~/.bashrc
@@ -89,19 +88,19 @@ echo "source /etc/bash_completion.d/abra" >> ~/.bashrc
 `, autocompletionFile))
 		case "zsh":
 			fmt.Println(fmt.Sprintf(`
-# Run the following commands to install auto-completion
+# run the following commands to install auto-completion
 sudo mkdir /etc/zsh/completion.d/
 sudo cp %s /etc/zsh/completion.d/abra
 echo "PROG=abra\n_CLI_ZSH_AUTOCOMPLETE_HACK=1\nsource /etc/zsh/completion.d/abra" >> ~/.zshrc
-# To test, run the following: "abra app <hit tab key>" - you should see command completion!
+# to test, run the following: "abra app <hit tab key>" - you should see command completion!
 `, autocompletionFile))
 		case "fish":
 			fmt.Println(fmt.Sprintf(`
-# Run the following commands to install auto-completion
+# run the following commands to install auto-completion
 sudo mkdir -p /etc/fish/completions
 sudo cp %s /etc/fish/completions/abra
 echo "source /etc/fish/completions/abra" >> ~/.config/fish/config.fish
-# To test, run the following: "abra app <hit tab key>" - you should see command completion!
+# to test, run the following: "abra app <hit tab key>" - you should see command completion!
 `, autocompletionFile))
 		}
 
@@ -113,14 +112,18 @@ echo "source /etc/fish/completions/abra" >> ~/.config/fish/config.fish
 var UpgradeCommand = cli.Command{
 	Name:    "upgrade",
 	Aliases: []string{"u"},
-	Usage:   "Upgrade Abra itself",
+	Usage:   "Upgrade abra",
 	Description: `
-Upgrade Abra in-place with the latest stable or release candidate.
+Upgrade abra in-place with the latest stable or release candidate.
 
-Pass "-r/--rc" to install the latest release candidate. Please bear in mind
+Use "-r/--rc" to install the latest release candidate. Please bear in mind that
-that it may contain catastrophic bugs. Thank you very much for the testing
+it may contain absolutely catastrophic deal-breaker bugs. Thank you very much
-efforts!
+for the testing efforts 💗
-`,
+
+EXAMPLE:
+
+    abra upgrade
+		abra upgrade --rc`,
 	Flags: []cli.Flag{internal.RCFlag},
 	Action: func(c *cli.Context) error {
 		mainURL := "https://install.abra.coopcloud.tech"
@@ -144,7 +147,7 @@ efforts!
 func newAbraApp(version, commit string) *cli.App {
 	app := &cli.App{
 		Name: "abra",
-		Usage: `The Co-op Cloud command-line utility belt 🎩🐇
+		Usage: `the Co-op Cloud command-line utility belt 🎩🐇
     ____                           ____ _                 _
    / ___|___         ___  _ __    / ___| | ___  _   _  __| |
   | |   / _ \ _____ / _ \| '_ \  | |   | |/ _ \| | | |/ _' |

cli/recipe/diff.go

@@ -5,14 +5,13 @@ import (
 	"coopcloud.tech/abra/pkg/autocomplete"
 	gitPkg "coopcloud.tech/abra/pkg/git"
 	"coopcloud.tech/abra/pkg/log"
-	"coopcloud.tech/abra/pkg/recipe"
 	"github.com/urfave/cli"
 )
 
 var recipeDiffCommand = cli.Command{
 	Name:        "diff",
 	Usage:       "Show unstaged changes in recipe config",
-	Description: "Due to limitations in our underlying Git dependency, this command requires /usr/bin/git.",
+	Description: "This command requires /usr/bin/git.",
 	Aliases:     []string{"d"},
 	ArgsUsage:   "<recipe>",
 	Flags: []cli.Flag{
@@ -22,12 +21,7 @@ var recipeDiffCommand = cli.Command{
 	Before:       internal.SubCommandBefore,
 	BashComplete: autocomplete.RecipeNameComplete,
 	Action: func(c *cli.Context) error {
-		recipeName := c.Args().First()
+		r := internal.ValidateRecipe(c)
-		r := recipe.Get(recipeName)
-
-		if recipeName != "" {
-			internal.ValidateRecipe(c)
-		}
 
 		if err := gitPkg.DiffUnstaged(r.Dir); err != nil {
 			log.Fatal(err)

cli/recipe/new.go

@@ -48,12 +48,7 @@ Create a new recipe.
 
 Abra uses the built-in example repository which is available here:
 
-    https://git.coopcloud.tech/coop-cloud/example
+    https://git.coopcloud.tech/coop-cloud/example`,
-
-Files within the example repository make use of the Golang templating system
-which Abra uses to inject values into the generated recipe folder (e.g. name of
-recipe and domain in the sample environment config).
-`,
 	Action: func(c *cli.Context) error {
 		recipeName := c.Args().First()
 		r := recipe.Get(recipeName)
@@ -100,22 +95,8 @@ recipe and domain in the sample environment config).
 			log.Fatal(err)
 		}
 
-		fmt.Print(fmt.Sprintf(`
+		log.Infof("new recipe '%s' created: %s", recipeName, path.Join(r.Dir))
-Your new %s recipe has been created in %s.
+		log.Info("happy hacking 🎉")
-
-In order to share your recipe, you can upload it the git repository to:
-
-    https://git.coopcloud.tech/coop-cloud/%s
-
-If you're not sure how to do that, come chat with us:
-
-    https://docs.coopcloud.tech/intro/contact
-
-See "abra recipe -h" for additional recipe maintainer commands.
-
-Happy Hacking!
-
-`, recipeName, path.Join(r.Dir), recipeName))
 
 		return nil
 	},

cli/recipe/recipe.go

@@ -18,9 +18,7 @@ for you.
 
 Anyone who uses a recipe can become a maintainer. Maintainers typically make
 sure the recipe is in good working order and the config upgraded in a timely
-manner. Abra supports convenient automation for recipe maintainenace, see the
+manner.`,
-"abra recipe upgrade", "abra recipe sync" and "abra recipe release" commands.
-`,
 	Subcommands: []cli.Command{
 		recipeFetchCommand,
 		recipeLintCommand,

cli/recipe/release.go

@@ -45,8 +45,7 @@ major and therefore require intervention while doing the upgrade work.
 
 Publish your new release to git.coopcloud.tech with "-p/--publish". This
 requires that you have permission to git push to these repositories and have
-your SSH keys configured on your account.
+your SSH keys configured on your account.`,
-`,
 	Flags: []cli.Flag{
 		internal.DebugFlag,
 		internal.NoInputFlag,

cli/recipe/reset.go

@@ -12,7 +12,7 @@ import (
 var recipeResetCommand = cli.Command{
 	Name:        "reset",
 	Usage:       "Remove all unstaged changes from recipe config",
-	Description: "WARNING, this will delete your changes. Be Careful.",
+	Description: "WARNING: this will delete your changes. Be Careful.",
 	Aliases:     []string{"rs"},
 	ArgsUsage:   "<recipe>",
 	Flags: []cli.Flag{

cli/recipe/sync.go

@@ -37,8 +37,7 @@ named "app") which corresponds to the following format:
 
 Where <version> can be specifed on the command-line or Abra can attempt to
 auto-generate it for you. The <recipe> configuration will be updated on the
-local file system.
+local file system.`,
-`,
 	BashComplete: autocomplete.RecipeNameComplete,
 	Action: func(c *cli.Context) error {
 		recipe := internal.ValidateRecipe(c)

cli/recipe/upgrade.go

@@ -53,10 +53,11 @@ The command is interactive and will show a select input which allows you to
 make a seclection. Use the "?" key to see more help on navigating this
 interface.
 
-You may invoke this command in "wizard" mode and be prompted for input:
+You may invoke this command in "wizard" mode and be prompted for input.
 
-    abra recipe upgrade
+EXAMPLE:
-`,
+
+    abra recipe upgrade`,
 	ArgsUsage: "<recipe>",
 	Flags: []cli.Flag{
 		internal.DebugFlag,

cli/recipe/version.go

@@ -24,11 +24,10 @@ func sortServiceByName(versions [][]string) func(i, j int) bool {
 }
 
 var recipeVersionCommand = cli.Command{
-	Name:        "versions",
+	Name:      "versions",
-	Aliases:     []string{"v"},
+	Aliases:   []string{"v"},
-	Usage:       "List recipe versions",
+	Usage:     "List recipe versions",
-	ArgsUsage:   "<recipe>",
+	ArgsUsage: "<recipe>",
-	Description: "Versions are read from the recipe catalogue.",
 	Flags: []cli.Flag{
 		internal.DebugFlag,
 		internal.OfflineFlag,

cli/server/add.go

@@ -94,7 +94,7 @@ func createServerDir(name string) (bool, error) {
 var serverAddCommand = cli.Command{
 	Name:    "add",
 	Aliases: []string{"a"},
-	Usage:   "Add a server to your configuration",
+	Usage:   "Add a new server to your configuration",
 	Description: `
 Add a new server to your configuration so that it can be managed by Abra.
 
@@ -121,8 +121,7 @@ You can also pass "--no-domain-checks/-D" flag to use any arbitrary name
 instead of a real domain. The host will be resolved with the "Hostname" entry
 of your ~/.ssh/config. Checks for a valid online domain will be skipped:
 
-  abra server add -D example
+  abra server add -D example`,
-`,
 	Flags: []cli.Flag{
 		internal.DebugFlag,
 		internal.NoInputFlag,

cli/server/prune.go

@@ -31,13 +31,12 @@ var volumesFilterFlag = &cli.BoolFlag{
 var serverPruneCommand = cli.Command{
 	Name:    "prune",
 	Aliases: []string{"p"},
-	Usage:   "Prune a managed server; Runs a docker system prune",
+	Usage:   "Prune resources on a server",
 	Description: `
 Prunes unused containers, networks, and dangling images.
 
-If passing "-v/--volumes" then volumes not connected to a deployed app will
+Use "-v/--volumes" to remove volumes that are not associated with a deployed
-also be removed. This can result in unwanted data loss if not used carefully.
+app. This can result in unwanted data loss if not used carefully.`,
-	`,
 	ArgsUsage: "[<server>]",
 	Flags: []cli.Flag{
 		allFilterFlag,

cli/server/remove.go

@@ -17,12 +17,12 @@ var serverRemoveCommand = cli.Command{
 	Aliases:   []string{"rm"},
 	ArgsUsage: "<server>",
 	Usage:     "Remove a managed server",
-	Description: `Remove a managed server.
+	Description: `
+Remove a managed server.
 
 Abra will remove the internal bookkeeping (~/.abra/servers/...) and underlying
 client connection context. This server will then be lost in time, like tears in
-rain.
+rain.`,
-`,
 	Flags: []cli.Flag{
 		internal.DebugFlag,
 		internal.NoInputFlag,

cli/updater/updater.go

@@ -54,10 +54,12 @@ var Notify = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-It reads the deployed app versions and looks for new versions in the recipe
+Read the deployed app versions and look for new versions in the recipe
-catalogue. If a new patch/minor version is available, a notification is
+catalogue.
-printed. To include major versions use the --major flag.
+
-`,
+If a new patch/minor version is available, a notification is printed.
+
+Use "--major" to include new major versions.`,
 	Action: func(c *cli.Context) error {
 		cl, err := client.New("default")
 		if err != nil {
@@ -103,14 +105,17 @@ var UpgradeApp = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-Upgrade an app by specifying its stack name and recipe. By passing "--all"
+Upgrade an app by specifying stack name and recipe. 
-instead, every deployed app is upgraded. For each apps with enabled auto
+
-updates the deployed version is compared with the current recipe catalogue
+Use "--all" to upgrade every deployed app.
-version. If a new patch/minor version is available, the app is upgraded. To
+
-include major versions use the "--major" flag. Don't do that, it will probably
+For each app with auto updates enabled, the deployed version is compared with
-break things. Only apps that are not deployed with "--chaos" are upgraded, to
+the current recipe catalogue version. If a new patch/minor version is
-update chaos deployments use the "--chaos" flag. Use it with care.
+available, the app is upgraded.
-`,
+
+To include major versions use the "--major" flag. You probably don't want that
+as it will break things. Only apps that are not deployed with "--chaos" are
+upgraded, to update chaos deployments use the "--chaos" flag. Use it with care.`,
 	Action: func(c *cli.Context) error {
 		cl, err := client.New("default")
 		if err != nil {