Improve Atmos help (#959)

* fix help for 'atmos about non-existent'

* Add invalid flag error handler

* Ignore update messages in tests

* fix test cases

* Add Markdown usage capability

* usage markdowns

* example hint updated

* fix tests

* Update usage display to markdown glamour

* CheckTTYSupport should be in term package

* atmost about usage and workflow usage

* Improved flag usage example

* update workflow error message

* updated usage

* Add custom alias to help

* Fix asci render logic for error

* fix testcases

* test updated

* Add --help suggestion to help

* removed examples from md

* fix doubledash suggestion

* fix test case

* fix no valid subcommands

* updated stack required and component errors to new error render format

* fix tests

* fix logger

* test fixes

* added test for alias subcommand

* Valid subcommands should be on next line

* Update cmd/workflow.go

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* added assertion back

* update error messages for atlantis to markdown

* [autofix.ci] apply automated fixes

* fix log level error

* fix rendering of examples

* Add markdown util

* Update pkg/ui/markdown/renderer.go

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* remove unwanted renderError function

* fix tests

* added more error checks

* added description comment

* fix ascii render logic and use consistent functions

* fix manual render issue

* Update cmd/validate_component.go

Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <erik@cloudposse.com>

* Update internal/exec/atlantis_generate_repo_config.go

Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <erik@cloudposse.com>

* Update cmd/docs.go

Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <erik@cloudposse.com>

* Update cmd/cmd_utils.go

Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <erik@cloudposse.com>

* updated error message for stack and components missing

* fix flag help

* Update pkg/ui/markdown/renderer.go

Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <erik@cloudposse.com>

* [autofix.ci] apply automated fixes

* fix the snapshots

* fixed workflow error message format

* workflow UX updated

* Update cmd/cmd_utils.go

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* small updates

* [autofix.ci] apply automated fixes

* fix tests

* make error condition for custom command invalid config usefull

* fix custom command invalid error sentence

* update tests

* updated terraform help

* readded this test

* [autofix.ci] apply automated fixes

* update tests

* update tests

* update tests

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <erik@cloudposse.com>
Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com>
Co-authored-by: aknysh <andriy.knysh@gmail.com>

Author: 5 people

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, "")
 		}
 	},
 	ValidArgsFunction: ComponentsArgCompletion,

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()
 	}
@@ -113,6 +119,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,
@@ -187,10 +222,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")
 		}
 	}
 
@@ -583,37 +617,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
@@ -637,6 +665,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)
+}
+
 func stackFlagCompletion(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 	output, err := listStacks(cmd)
 	if err != nil {

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, "")
 		}
 	},
 	ValidArgsFunction: ComponentsArgCompletion,

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

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