Better CLI Help Messages (#505)

src/cmd/agent.go

@@ -8,6 +8,9 @@ import (
 var agentCmd = &cobra.Command{
 	Use:   "agent",
 	Short: "Runs the zarf agent",
+	Long: "NOTE: This command is a hidden command and generally shouldn't be run by a human.\n" +
+		"This command starts up a http webhook that Zarf deployments use to mutate pods to conform " +
+		"with the Zarf container registry and Gitea server URLs.",
 	// this command should not be advertised on the cli as it has no value outside the k8s env
 	Hidden: true,
 	Run: func(cmd *cobra.Command, args []string) {

src/cmd/connect.go

@@ -17,6 +17,16 @@ var (
 		Use:     "connect <REGISTRY|LOGGING|GIT>",
 		Aliases: []string{"c"},
 		Short:   "Access services or pods deployed in the cluster.",
+		Long: "Uses a k8s port-forward to connect to resources within the cluster referenced by your kube-context.\n" +
+			"Three default options for this command are <REGISTRY|LOGGING|GIT>. These will connect to the Zarf created resources " +
+			"(assuming they were selected when performing the `zarf init` command).\n\n" +
+			"Packages can provide service manifests that define their own shortcut connection options. These options will be " +
+			"printed to the terminal when the package finishes deploying.\n If you don't remember what connection shortcuts your deployed " +
+			"package offers, you can search your cluster for services that have the 'zarf.dev/connect-name' label. The value of that label is " +
+			"the name you will pass into the 'zarf connect' command. \n\n" +
+			"Even if the packages you deploy don't define their own shortcut connection options, you can use the command flags " +
+			"to connect into specific resources. You can read the command flag descriptions below to get a better idea how to connect " +
+			"to whatever resource you are trying to connect to.",
 		Run: func(cmd *cobra.Command, args []string) {
 			var target string
 			if len(args) > 0 {

src/cmd/destroy.go

@@ -23,6 +23,16 @@ var destroyCmd = &cobra.Command{
 	Use:     "destroy",
 	Aliases: []string{"d"},
 	Short:   "Tear it all down, we'll miss you Zarf...",
+	Long: "Tear down Zarf.\n\n" +
+		"Deletes everything in the 'zarf' namespace within your connected k8s cluster.\n\n" +
+		"If Zarf deployed your k8s cluster, this command will also tear your cluster down by" +
+		"searching through /opt/zarf for any scripts that start with 'zarf-clean-' and executing them. " +
+		"Since this is a cleanup operation, Zarf will not stop the teardown if one of the scripts produce " +
+		"an error.\n\n" +
+		"If Zarf did not deploy your k8s cluster, this command will delete the Zarf namespace, delete secrets " +
+		"and labels that only Zarf cares about, and optionally uninstall components that Zarf deployed onto " +
+		"the cluster. Since this is a cleanup operation, Zarf will not stop the uninstalls if one of the " +
+		"resources produce an error while being deleted.",
 	Run: func(cmd *cobra.Command, args []string) {
 		// NOTE: If 'zarf init' failed to deploy the k3s component (or if we're looking at the wrong kubeconfig)
 		//       there will be no zarf-state to load and the struct will be empty. In these cases, if we can find
@@ -41,7 +51,7 @@ var destroyCmd = &cobra.Command{
 			// Run all the scripts!
 			pattern := regexp.MustCompile(`(?mi)zarf-clean-.+\.sh$`)
 			scripts := utils.RecursiveFileList(config.ZarfCleanupScriptsPath, pattern)
-			// Iterate over al matching zarf-clean scripts and exec them
+			// Iterate over all matching zarf-clean scripts and exec them
 			for _, script := range scripts {
 				// Run the matched script
 				_, _, err := utils.ExecCommandWithContext(context.TODO(), true, script)
@@ -50,6 +60,8 @@ var destroyCmd = &cobra.Command{
 
 					// Don't remove scripts we can't execute so the user can try to manually run
 					continue
+				} else if err != nil {
+					message.Debugf("Received error when trying to execute the script (%v): %v", script, err)
 				}
 
 				// Try to remove the script, but ignore any errors
@@ -75,7 +87,7 @@ var destroyCmd = &cobra.Command{
 func init() {
 	rootCmd.AddCommand(destroyCmd)
 
-	destroyCmd.Flags().BoolVar(&confirmDestroy, "confirm", false, "Confirm the destroy action")
+	destroyCmd.Flags().BoolVar(&confirmDestroy, "confirm", false, "REQUIRED. Confirm the destroy action to prevent accidental deletions")
 	destroyCmd.Flags().BoolVar(&removeComponents, "remove-components", false, "Also remove any installed components outside the zarf namespace")
 	_ = destroyCmd.MarkFlagRequired("confirm")
 }

src/cmd/initialize.go

@@ -18,8 +18,19 @@ import (
 var initCmd = &cobra.Command{
 	Use:     "init",
 	Aliases: []string{"i"},
-	Short:   "Deploys the gitops service or appliance cluster on a clean linux box",
-	Long:    "Flags are only required if running via automation, otherwise the init command will prompt you for your configuration choices",
+	Short:   "Prepares a k8s cluster for the deployment of Zarf packages",
+	Long: "Injects a docker registry as well as other optional useful things (such as a git server " +
+		"and a logging stack) into a k8s cluster under the 'zarf' namespace " +
+		"to support future application deployments. \n" +
+
+		"If you do not have a k8s cluster already configured, this command will give you " +
+		"the ability to install a cluster locally.\n\n" +
+
+		"This command looks for a zarf-init package in the local directory that the command was executed " +
+		"from. If no package is found in the local directory and the Zarf CLI exists somewhere outside of " +
+		"the current directory, Zarf will failover and attempt to find a zarf-init package in the directory " +
+		"that the Zarf binary is located in.\n",
+
 	Run: func(cmd *cobra.Command, args []string) {
 		zarfLogo := message.GetLogo()
 		_, _ = fmt.Fprintln(os.Stderr, zarfLogo)
@@ -46,8 +57,7 @@ var initCmd = &cobra.Command{
 func init() {
 	rootCmd.AddCommand(initCmd)
 	initCmd.Flags().BoolVar(&config.DeployOptions.Confirm, "confirm", false, "Confirm the install without prompting")
-	initCmd.Flags().StringVar(&config.DeployOptions.Components, "components", "", "Comma-separated list of components to install.  Adding this flag will skip the init prompts for which components to install")
-
+	initCmd.Flags().StringVar(&config.DeployOptions.Components, "components", "", "Comma-separated list of components to install.")
 	initCmd.Flags().StringVar(&config.DeployOptions.StorageClass, "storage-class", "", "Describe the StorageClass to be used")
 	initCmd.Flags().StringVar(&config.DeployOptions.Secret, "secret", "", "Root secret value that is used to 'seed' other secrets")
 	initCmd.Flags().StringVar(&config.DeployOptions.NodePort, "nodeport", "", "Nodeport to access the Zarf container registry. Between [30000-32767]")

src/cmd/package.go

@@ -2,10 +2,11 @@ package cmd
 
 import (
 	"fmt"
-	"github.com/defenseunicorns/zarf/src/internal/message"
 	"path/filepath"
 	"regexp"
 
+	"github.com/defenseunicorns/zarf/src/internal/message"
+
 	"github.com/AlecAivazis/survey/v2"
 	"github.com/defenseunicorns/zarf/src/config"
 	"github.com/defenseunicorns/zarf/src/internal/packager"
@@ -26,6 +27,9 @@ var packageCreateCmd = &cobra.Command{
 	Use:     "create",
 	Aliases: []string{"c"},
 	Short:   "Create an update package to push to the gitops server (runs online)",
+	Long: "Builds a tarball of resources and dependencies defined by the 'zarf.yaml' located in the working directory.\n" +
+		"Private registries and repositories are accessed via credentials in your local '~/.docker/config.json' " +
+		"and '~/.git-credentials'.\n",
 	Run: func(cmd *cobra.Command, args []string) {
 		if cmd.Flag("zarf-cache").Changed && cachePathClean(zarfImageCache) {
 			config.SetImageCachePath(zarfImageCache)
@@ -38,6 +42,7 @@ var packageDeployCmd = &cobra.Command{
 	Use:     "deploy [PACKAGE]",
 	Aliases: []string{"d"},
 	Short:   "Deploys an update package from a local file or URL (runs offline)",
+	Long:    "Uses current kubecontext to deploy the packaged tarball onto a k8s cluster.",
 	Args:    cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		var done func()
@@ -51,8 +56,12 @@ var packageDeployCmd = &cobra.Command{
 var packageInspectCmd = &cobra.Command{
 	Use:     "inspect [PACKAGE]",
 	Aliases: []string{"i"},
-	Short:   "lists the payload of an update package file (runs offline)",
-	Args:    cobra.MaximumNArgs(1),
+	Short:   "Lists the payload of a compiled package file (runs offline)",
+	Long: "Lists the payload of a compiled package file (runs offline)\n" +
+		"Unpacks the package tarball into a temp directory and displays the " +
+		"contents of the zarf.yaml package definition as well as the version " +
+		"of the Zarf CLI that was used to build the package.",
+	Args: cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		packageName := choosePackage(args)
 		packager.Inspect(packageName)

src/cmd/prepare.go

@@ -72,7 +72,9 @@ var prepareComputeFileSha256sum = &cobra.Command{
 var prepareFindImages = &cobra.Command{
 	Use:     "find-images",
 	Aliases: []string{"prep"},
-	Short:   "evaluates components in a zarf file to identify images specified in their helm charts and manifests",
+	Short:   "Evaluates components in a zarf file to identify images specified in their helm charts and manifests",
+	Long: "Evaluates components in a zarf file to identify images specified in their helm charts and manifests.\n\n" +
+		"Components that have repos that host helm charts can be processed by providing the --repo-chart-path.",
 	Run: func(cmd *cobra.Command, args []string) {
 		packager.FindImages(repoHelmChartPath)
 	},

src/cmd/tools.go

@@ -30,7 +30,7 @@ var toolsCmd = &cobra.Command{
 var archiverCmd = &cobra.Command{
 	Use:     "archiver",
 	Aliases: []string{"a"},
-	Short:   "Compress/Decompress tools",
+	Short:   "Compress/Decompress tools for Zarf packages",
 }
 
 var archiverCompressCmd = &cobra.Command{
@@ -50,7 +50,7 @@ var archiverCompressCmd = &cobra.Command{
 var archiverDecompressCmd = &cobra.Command{
 	Use:     "decompress [ARCHIVE] [DESTINATION]",
 	Aliases: []string{"d"},
-	Short:   "Decompress an archive to a specified location.",
+	Short:   "Decompress an archive (package) to a specified location.",
 	Args:    cobra.ExactArgs(2),
 	Run: func(cmd *cobra.Command, args []string) {
 		sourceArchive, destinationPath := args[0], args[1]
@@ -112,6 +112,9 @@ var k9sCmd = &cobra.Command{
 var createReadOnlyGiteaUser = &cobra.Command{
 	Use:    "create-read-only-gitea-user",
 	Hidden: true,
+	Short:  "Creates a read-only user in Gitea",
+	Long: "Creates a read-only user in Gitea by using the Gitea API. " +
+		"This is called internally by the supported Gitea package component.",
 	Run: func(cmd *cobra.Command, args []string) {
 		// Load the state so we can get the credentials for the admin git user
 		state := k8s.LoadZarfState()
@@ -127,6 +130,7 @@ var createReadOnlyGiteaUser = &cobra.Command{
 
 var generateCLIDocs = &cobra.Command{
 	Use:    "generate-cli-docs",
+	Short:  "Creates auto-generated markdown of all the commands for the CLI",
 	Hidden: true,
 	Run: func(cmd *cobra.Command, args []string) {
 		utils.CreateDirectory("clidocs", 0700)

src/cmd/version.go

@@ -10,7 +10,8 @@ import (
 var versionCmd = &cobra.Command{
 	Use:     "version",
 	Aliases: []string{"v"},
-	Short:   "Displays the version the zarf binary was built from",
+	Short:   "Displays the version of the Zarf binary",
+	Long:    "Displays the version of the Zarf release that the Zarf binary was built from.",
 	Run: func(cmd *cobra.Command, args []string) {
 		fmt.Println(config.CLIVersion)
 	},