Improve Atmos help

cmd/about.go

@@ -2,10 +2,8 @@ package cmd
 
 import (
 	_ "embed"
-	"fmt"
-	"os"
 
-	"github.com/charmbracelet/glamour"
+	"github.com/cloudposse/atmos/pkg/utils"
 	"github.com/spf13/cobra"
 )
 
@@ -14,31 +12,12 @@ var aboutMarkdown string
 
 // aboutCmd represents the about command
 var aboutCmd = &cobra.Command{
-	Use:                "about",
-	Short:              "Learn about Atmos",
-	Long:               `Display information about Atmos, its features, and benefits.`,
-	Args:               cobra.NoArgs,
-	DisableSuggestions: true,
-	SilenceUsage:       true,
-	SilenceErrors:      true,
+	Use:   "about",
+	Short: "Learn about Atmos",
+	Long:  `Display information about Atmos, its features, and benefits.`,
+	Args:  cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
-		renderer, err := glamour.NewTermRenderer(
-			glamour.WithAutoStyle(),
-			glamour.WithWordWrap(80),
-		)
-		if err != nil {
-			return fmt.Errorf("failed to create markdown renderer: %w", err)
-		}
-
-		out, err := renderer.Render(aboutMarkdown)
-		if err != nil {
-			return fmt.Errorf("failed to render about documentation: %w", err)
-		}
-
-		_, err = fmt.Fprint(os.Stdout, out)
-		if err != nil {
-			return err
-		}
+		utils.PrintfMarkdown(aboutMarkdown)
 		return nil
 	},
 }

cmd/atlantis.go

@@ -14,5 +14,6 @@ var atlantisCmd = &cobra.Command{
 }
 
 func init() {
+	atlantisCmd.PersistentFlags().Bool("", false, doubleDashHint)
 	RootCmd.AddCommand(atlantisCmd)
 }

cmd/atlantis_generate_repo_config.go

@@ -4,7 +4,7 @@ import (
 	"github.com/spf13/cobra"
 
 	e "github.com/cloudposse/atmos/internal/exec"
-	u "github.com/cloudposse/atmos/pkg/utils"
+	"github.com/cloudposse/atmos/pkg/utils"
 )
 
 // atlantisGenerateRepoConfigCmd generates repository configuration for Atlantis
@@ -22,7 +22,7 @@ var atlantisGenerateRepoConfigCmd = &cobra.Command{
 		checkAtmosConfig()
 		err := e.ExecuteAtlantisGenerateRepoConfigCmd(cmd, args)
 		if err != nil {
-			u.LogErrorAndExit(err)
+			utils.PrintErrorMarkdownAndExit("", err, "")
 		}
 	},
 }

cmd/aws.go

@@ -14,5 +14,6 @@ var awsCmd = &cobra.Command{
 }
 
 func init() {
+	awsCmd.PersistentFlags().Bool("", false, doubleDashHint)
 	RootCmd.AddCommand(awsCmd)
 }

cmd/aws_eks_update_kubeconfig.go

@@ -35,7 +35,7 @@ See https://docs.aws.amazon.com/cli/latest/reference/eks/update-kubeconfig.html
 	Run: func(cmd *cobra.Command, args []string) {
 		err := e.ExecuteAwsEksUpdateKubeconfigCommand(cmd, args)
 		if err != nil {
-			u.LogErrorAndExit(err)
+			u.PrintErrorMarkdownAndExit("", err, "")
 		}
 	},
 }

cmd/cmd_utils.go

@@ -46,6 +46,12 @@ func processCustomCommands(
 	var command *cobra.Command
 	existingTopLevelCommands := make(map[string]*cobra.Command)
 
+	// Build commands and their hierarchy from the alias map
+	for alias, fullCmd := range atmosConfig.CommandAliases {
+		parts := strings.Fields(fullCmd)
+		addCommandWithAlias(RootCmd, alias, parts)
+	}
+
 	if topLevel {
 		existingTopLevelCommands = getTopLevelCommands()
 	}
@@ -112,6 +118,35 @@ func processCustomCommands(
 	return nil
 }
 
+// addCommandWithAlias adds a command hierarchy based on the full command
+func addCommandWithAlias(parentCmd *cobra.Command, alias string, parts []string) {
+	if len(parts) == 0 {
+		return
+	}
+
+	// Check if a command with the current part already exists
+	var cmd *cobra.Command
+	for _, c := range parentCmd.Commands() {
+		if c.Use == parts[0] {
+			cmd = c
+			break
+		}
+	}
+
+	// If the command doesn't exist, create it
+	if cmd == nil {
+		u.LogErrorAndExit(fmt.Errorf("subcommand `%s` not found for alias `%s`", parts[0], alias))
+	}
+
+	// If there are more parts, recurse for the next level
+	if len(parts) > 1 {
+		addCommandWithAlias(cmd, alias, parts[1:])
+	} else if !Contains(cmd.Aliases, alias) {
+		// This is the last part of the command, add the alias
+		cmd.Aliases = append(cmd.Aliases, alias)
+	}
+}
+
 // processCommandAliases processes the command aliases
 func processCommandAliases(
 	atmosConfig schema.AtmosConfiguration,
@@ -186,10 +221,9 @@ func preCustomCommand(
 			os.Exit(1)
 		} else {
 			// truly invalid, nothing to do
-			u.LogError(errors.New(
-				"invalid command: no args, no steps, no sub-commands",
-			))
-			os.Exit(1)
+			u.PrintErrorMarkdownAndExit("Invalid command", errors.New(
+				fmt.Sprintf("The `%s` command has no steps or subcommands configured.", cmd.CommandPath()),
+			), "https://atmos.tools/cli/configuration/commands")
 		}
 	}
 
@@ -552,37 +586,31 @@ func handleHelpRequest(cmd *cobra.Command, args []string) {
 	}
 }
 
+// showUsageAndExit we display the markdown usage or fallback to our custom usage
+// Markdown usage is not compatible with all outputs. We should therefore have fallback option.
 func showUsageAndExit(cmd *cobra.Command, args []string) {
-	var suggestions []string
-	unknownCommand := fmt.Sprintf("Error: Unknown command: %q\n\n", cmd.CommandPath())
-
+	if len(args) == 0 {
+		showErrorExampleFromMarkdown(cmd, "")
+	}
 	if len(args) > 0 {
-		suggestions = cmd.SuggestionsFor(args[0])
-		unknownCommand = fmt.Sprintf("Error: Unknown command %q for %q\n\n", args[0], cmd.CommandPath())
+		showErrorExampleFromMarkdown(cmd, args[0])
 	}
-	u.PrintErrorInColor(unknownCommand)
-	if len(suggestions) > 0 {
-		u.PrintMessage("Did you mean this?")
-		for _, suggestion := range suggestions {
-			u.PrintMessage(fmt.Sprintf("  %s\n", suggestion))
-		}
-	} else {
-		// Retrieve valid subcommands dynamically
-		validSubcommands := []string{}
-		for _, subCmd := range cmd.Commands() {
-			validSubcommands = append(validSubcommands, subCmd.Name())
-		}
-		if len(validSubcommands) > 0 {
-			u.PrintMessage("Valid subcommands are:")
-			for _, sub := range validSubcommands {
-				u.PrintMessage(fmt.Sprintf("  %s", sub))
-			}
+	os.Exit(1)
+}
+
+func showFlagUsageAndExit(cmd *cobra.Command, err error) error {
+	unknownCommand := fmt.Sprintf("%v for command `%s`\n\n", err.Error(), cmd.CommandPath())
+	args := strings.Split(err.Error(), ": ")
+	if len(args) == 2 {
+		if strings.Contains(args[0], "flag needs an argument") {
+			unknownCommand = fmt.Sprintf("`%s` %s for command `%s`\n\n", args[1], args[0], cmd.CommandPath())
 		} else {
-			u.PrintMessage("No valid subcommands found")
+			unknownCommand = fmt.Sprintf("%s `%s` for command `%s`\n\n", args[0], args[1], cmd.CommandPath())
 		}
 	}
-	u.PrintMessage(fmt.Sprintf("\nRun '%s --help' for usage", cmd.CommandPath()))
+	showUsageExample(cmd, unknownCommand)
 	os.Exit(1)
+	return nil
 }
 
 // getConfigAndStacksInfo processes the CLI config and stacks
@@ -606,6 +634,45 @@ func getConfigAndStacksInfo(commandName string, cmd *cobra.Command, args []strin
 	return info
 }
 
+func showErrorExampleFromMarkdown(cmd *cobra.Command, arg string) {
+	commandPath := cmd.CommandPath()
+	suggestions := []string{}
+	details := fmt.Sprintf("The command `%s` is not valid usage\n", commandPath)
+	if len(arg) > 0 {
+		details = fmt.Sprintf("Unknown command `%s` for `%s`\n", arg, commandPath)
+	} else if len(cmd.Commands()) != 0 && arg == "" {
+		details = fmt.Sprintf("The command `%s` requires a subcommand\n", commandPath)
+	}
+	if len(arg) > 0 {
+		suggestions = cmd.SuggestionsFor(arg)
+	}
+	if len(suggestions) > 0 {
+		details = details + "Did you mean this?\n"
+		for _, suggestion := range suggestions {
+			details += "* " + suggestion + "\n"
+		}
+	} else {
+		if len(cmd.Commands()) > 0 {
+			details += "\nValid subcommands are:\n"
+		}
+		// Retrieve valid subcommands dynamically
+		for _, subCmd := range cmd.Commands() {
+			details = details + "* " + subCmd.Name() + "\n"
+		}
+	}
+	showUsageExample(cmd, details)
+}
+
+func showUsageExample(cmd *cobra.Command, details string) {
+	contentName := strings.ReplaceAll(cmd.CommandPath(), " ", "_")
+	suggestion := fmt.Sprintf("\n\nRun `%s --help` for usage", cmd.CommandPath())
+	if exampleContent, ok := examples[contentName]; ok {
+		suggestion = exampleContent.Suggestion
+		details += "\n## Usage Examples:\n" + exampleContent.Content
+	}
+	u.PrintInvalidUsageErrorAndExit(errors.New(details), suggestion)
+}
+
 // Contains checks if a slice of strings contains an exact match for the target string.
 func Contains(slice []string, target string) bool {
 	for _, item := range slice {

cmd/describe_affected.go

@@ -20,7 +20,7 @@ var describeAffectedCmd = &cobra.Command{
 
 		err := e.ExecuteDescribeAffectedCmd(cmd, args)
 		if err != nil {
-			u.LogErrorAndExit(err)
+			u.PrintErrorMarkdownAndExit("", err, "")
 		}
 	},
 }

cmd/describe_component.go

@@ -19,7 +19,7 @@ var describeComponentCmd = &cobra.Command{
 
 		err := e.ExecuteDescribeComponentCmd(cmd, args)
 		if err != nil {
-			u.LogErrorAndExit(err)
+			u.PrintErrorMarkdownAndExit("", err, "")
 		}
 	},
 }

cmd/describe_config.go

@@ -17,7 +17,7 @@ var describeConfigCmd = &cobra.Command{
 	Run: func(cmd *cobra.Command, args []string) {
 		err := e.ExecuteDescribeConfigCmd(cmd, args)
 		if err != nil {
-			u.LogErrorAndExit(err)
+			u.PrintErrorMarkdown("", err, "")
 		}
 	},
 }

cmd/describe_dependents.go

@@ -20,7 +20,7 @@ var describeDependentsCmd = &cobra.Command{
 
 		err := e.ExecuteDescribeDependentsCmd(cmd, args)
 		if err != nil {
-			u.LogErrorAndExit(err)
+			u.PrintErrorMarkdownAndExit("", err, "")
 		}
 	},
 }

cmd/describe_stacks.go

@@ -20,7 +20,7 @@ var describeStacksCmd = &cobra.Command{
 
 		err := e.ExecuteDescribeStacksCmd(cmd, args)
 		if err != nil {
-			u.LogErrorAndExit(err)
+			u.PrintErrorMarkdownAndExit("", err, "")
 		}
 	},
 }

cmd/describe_workflows.go

@@ -24,7 +24,7 @@ var describeWorkflowsCmd = &cobra.Command{
 	Run: func(cmd *cobra.Command, args []string) {
 		err := e.ExecuteDescribeWorkflowsCmd(cmd, args)
 		if err != nil {
-			u.LogErrorAndExit(err)
+			u.PrintErrorMarkdownAndExit("", err, "")
 		}
 	},
 }

cmd/docs.go

@@ -36,7 +36,7 @@ var docsCmd = &cobra.Command{
 
 			atmosConfig, err := cfg.InitCliConfig(info, true)
 			if err != nil {
-				u.LogErrorAndExit(err)
+				u.PrintErrorMarkdownAndExit("", err, "")
 			}
 
 			// Detect terminal width if not specified in `atmos.yaml`
@@ -66,10 +66,10 @@ var docsCmd = &cobra.Command{
 			componentPath := filepath.Join(atmosConfig.BasePath, atmosConfig.Components.Terraform.BasePath, info.Component)
 			componentPathExists, err := u.IsDirectory(componentPath)
 			if err != nil {
-				u.LogErrorAndExit(err)
+				u.PrintErrorMarkdownAndExit("", err, "")
 			}
 			if !componentPathExists {
-				u.LogErrorAndExit(fmt.Errorf("Component '%s' not found in path: '%s'", info.Component, componentPath))
+				u.PrintErrorMarkdownAndExit("", fmt.Errorf("Component `%s` not found in path: `%s`", info.Component, componentPath), "")
 			}
 
 			readmePath := filepath.Join(componentPath, "README.md")

cmd/helmfile.go

@@ -20,6 +20,7 @@ func init() {
 	// https://github.com/spf13/cobra/issues/739
 	helmfileCmd.DisableFlagParsing = true
 	helmfileCmd.PersistentFlags().StringP("stack", "s", "", "atmos helmfile <helmfile_command> <component> -s <stack>")
+	helmfileCmd.PersistentFlags().Bool("", false, doubleDashHint)
 	RootCmd.AddCommand(helmfileCmd)
 }
 
@@ -30,6 +31,6 @@ func helmfileRun(cmd *cobra.Command, commandName string, args []string) {
 	info := getConfigAndStacksInfo("helmfile", cmd, diffArgs)
 	err := e.ExecuteHelmfile(info)
 	if err != nil {
-		u.LogErrorAndExit(err)
+		u.PrintErrorMarkdownAndExit("", err, "")
 	}
 }

cmd/helmfile_generate_varfile.go

@@ -32,7 +32,7 @@ func init() {
 
 	err := helmfileGenerateVarfileCmd.MarkPersistentFlagRequired("stack")
 	if err != nil {
-		u.LogErrorAndExit(err)
+		u.PrintErrorMarkdownAndExit("", err, "")
 	}
 
 	helmfileGenerateCmd.AddCommand(helmfileGenerateVarfileCmd)

cmd/list_components.go

@@ -3,7 +3,6 @@ package cmd
 import (
 	"fmt"
 
-	"github.com/fatih/color"
 	"github.com/spf13/cobra"
 
 	e "github.com/cloudposse/atmos/internal/exec"
@@ -30,26 +29,26 @@ var listComponentsCmd = &cobra.Command{
 
 		stackFlag, err := flags.GetString("stack")
 		if err != nil {
-			u.PrintMessageInColor(fmt.Sprintf("Error getting the 'stack' flag: %v", err), color.New(color.FgRed))
+			u.PrintInvalidUsageErrorAndExit(fmt.Errorf("Error getting the `stack` flag: `%v`", err), "")
 			return
 		}
 
 		configAndStacksInfo := schema.ConfigAndStacksInfo{}
 		atmosConfig, err := config.InitCliConfig(configAndStacksInfo, true)
 		if err != nil {
-			u.PrintMessageInColor(fmt.Sprintf("Error initializing CLI config: %v", err), theme.Colors.Error)
+			u.PrintErrorMarkdownAndExit("Error Initializing CLI config", err, "")
 			return
 		}
 
 		stacksMap, err := e.ExecuteDescribeStacks(atmosConfig, "", nil, nil, nil, false, false, false, false, nil)
 		if err != nil {
-			u.PrintMessageInColor(fmt.Sprintf("Error describing stacks: %v", err), theme.Colors.Error)
+			u.PrintErrorMarkdownAndExit("Error describing stacks", err, "")
 			return
 		}
 
 		output, err := l.FilterAndListComponents(stackFlag, stacksMap)
 		if err != nil {
-			u.PrintMessageInColor(fmt.Sprintf("Error: %v"+"\n", err), theme.Colors.Warning)
+			u.PrintErrorMarkdownAndExit("", err, "")
 			return
 		}