docs: more CLI documentation

cli/app.go

@@ -19,7 +19,22 @@ import (
 )
 
 var appNewCommand = &cli.Command{
-	Name: "new",
+	Name:  "new",
+	Usage: "Create a new app",
+	Description: `
+This command takes a recipe and uses it to cook up a new app. This app
+configuration is stored in your ~/.abra directory under the appropriate server.
+This command does not deploy your app for you. You will need to run "abra app
+deploy <app>" to do so.
+
+You can see what apps can be created by running "abra recipe ls".
+
+Passing the "--secrets" flag will automatically generate secrets for your app
+and store them encrypted at rest on the chosen target server. These generated
+secrets are only visible at generation time, so please take care to store them
+somewhere safe. You can use the "--pass" to store these generated passwords
+locally in a pass store (see passwordstore.org for more).
+`,
 	Flags: []cli.Flag{
 		ServerFlag,
 		DomainFlag,
@@ -207,6 +222,11 @@ var appSecretCommand = &cli.Command{
 var AppCommand = &cli.Command{
 	Name:  "app",
 	Usage: "Manage your apps",
+	Description: `
+This command provides all the functionality you need to manage the lifecycle of
+your apps. From initial deployment to day-2 operations (e.g. backup/restore) to
+scaling apps up and spinning them down.
+`,
 	Subcommands: []*cli.Command{
 		appNewCommand,
 		appConfigCommand,

cli/recipe.go

@@ -169,6 +169,7 @@ func ReadAppsCatalogueWeb(target interface{}) error {
 
 var recipeListCommand = &cli.Command{
 	Name:    "list",
+	Usage:   "List all available recipes",
 	Aliases: []string{"ls"},
 	Action: func(c *cli.Context) error {
 		catalogue, err := ReadAppsCatalogue()
@@ -297,6 +298,16 @@ var recipeCreateCommand = &cli.Command{
 var RecipeCommand = &cli.Command{
 	Name:  "recipe",
 	Usage: "Manage app recipes",
+	Description: `
+A recipe is a blueprint for a Co-op Cloud app. It is made up of two things:
+
+- A libre software app (e.g. Nextcloud, Wordpress, Mastodon)
+- A package configuration which describes how to deploy and maintain it
+
+Recipes are developed, maintained and extended by the Co-op Cloud volunteer-run
+community. Each recipe has a "level" which is intended as a way to quickly show
+how reliable this app is to deploy and maintain in its current state.
+`,
 	Subcommands: []*cli.Command{
 		recipeListCommand,
 		recipeVersionCommand,