Improve Atmos help

cmd/about.go

@@ -14,13 +14,10 @@ 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(),

cmd/atlantis.go

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

cmd/aws.go

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

cmd/cmd_utils.go

@@ -553,12 +553,17 @@ 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) {
-
+	if len(args) == 0 {
+		showErrorExampleFromMarkdown(cmd.CommandPath(), "")
+	}
 	var suggestions []string
 	unknownCommand := fmt.Sprintf("Error: Unknown command: %q\n\n", cmd.CommandPath())
 
 	if len(args) > 0 {
+		showErrorExampleFromMarkdown(cmd.CommandPath(), args[0])
 		suggestions = cmd.SuggestionsFor(args[0])
 		unknownCommand = fmt.Sprintf("Error: Unknown command %q for %q\n\n", args[0], cmd.CommandPath())
 	}
@@ -587,6 +592,14 @@ func showUsageAndExit(cmd *cobra.Command, args []string) {
 	os.Exit(1)
 }
 
+func showFlagUsageAndExit(cmd *cobra.Command, err error) error {
+	unknownCommand := fmt.Sprintf("Error: %v for command %q\n\n", err.Error(), cmd.CommandPath())
+	u.PrintErrorInColor(unknownCommand)
+	u.PrintMessage(fmt.Sprintf("Run '%s --help' for usage", cmd.CommandPath()))
+	os.Exit(1)
+	return nil
+}
+
 // getConfigAndStacksInfo gets the
 func getConfigAndStacksInfo(commandName string, cmd *cobra.Command, args []string) schema.ConfigAndStacksInfo {
 	// Check Atmos configuration

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)
 }
 

cmd/markdown/atmos_terraform_apply_usage.md

@@ -0,0 +1,7 @@
+Examples:
+
+  – Execute a terraform apply
+
+```
+    $ atmos terraform apply <component-name> -s <stack-name>
+```

cmd/markdown/atmos_terraform_plan_usage.md

@@ -0,0 +1,7 @@
+Examples:
+
+  – Execute a terraform plan
+
+```
+    $ atmos terraform plan <component-name> -s <stack-name>
+```

cmd/markdown/atmos_terraform_usage.md

@@ -0,0 +1,7 @@
+Examples:
+
+  – Execute a terraform
+
+```
+    $ atmos terraform [sub-command] <component-name> -s <stack-name>
+```

cmd/markdown_help.go

@@ -0,0 +1,36 @@
+package cmd
+
+import _ "embed"
+
+//go:embed markdown/atmos_terraform_usage.md
+var terraform string
+
+//go:embed markdown/atmos_terraform_plan_usage.md
+var terraformPlan string
+
+//go:embed markdown/atmos_terraform_apply_usage.md
+var terraformApply string
+
+type ExampleContent struct {
+	Content    string
+	Suggestion string
+}
+
+var doubleDashHint string = "Double dashes can be used to signify the end of Atmos-specific options and the beginning of additional native arguments and flags for the specific command being run."
+
+var examples map[string]ExampleContent = map[string]ExampleContent{
+	"atmos_terraform": {
+		Content:    terraform,
+		Suggestion: "https://atmos.tools/cli/commands/terraform/usage",
+	},
+	"atmos_terraform_plan": {
+		Content: terraformPlan,
+		// TODO: We should update this once we have a page for terraform plan
+		Suggestion: "https://atmos.tools/cli/commands/terraform/usage",
+	},
+	"atmos_terraform_apply": {
+		Content: terraformApply,
+		// TODO: We should update this once we have a page for terraform plan
+		Suggestion: "https://atmos.tools/cli/commands/terraform/usage",
+	},
+}

cmd/root.go

@@ -169,6 +169,9 @@ func initCobraConfig() {
 	styles := boa.DefaultStyles()
 	b := boa.New(boa.WithStyles(styles))
 	oldUsageFunc := RootCmd.UsageFunc()
+	RootCmd.SetFlagErrorFunc(func(c *cobra.Command, err error) error {
+		return showFlagUsageAndExit(c, err)
+	})
 	RootCmd.SetUsageFunc(func(c *cobra.Command) error {
 		if c.Use == "atmos" {
 			return b.UsageFunc(c)
@@ -215,3 +218,23 @@ func initCobraConfig() {
 // https://pkg.go.dev/github.com/c-bata/go-prompt
 // https://pkg.go.dev/github.com/spf13/cobra
 // https://scene-si.org/2017/04/20/managing-configuration-with-viper/
+
+func showErrorExampleFromMarkdown(commandPath string, arg string) {
+	contentName := strings.ReplaceAll(commandPath, " ", "_")
+	if exampleContent, ok := examples[contentName]; ok {
+		details := fmt.Sprintf("The command `%s` is not valid\n\n%s", commandPath, exampleContent.Content)
+
+		if len(arg) > 0 {
+			details = fmt.Sprintf("The command `%s` is not valid\n\n%s", commandPath+" "+arg, exampleContent.Content)
+		}
+
+		if err := renderError(ErrorMessage{
+			Title:      "Invalid Command",
+			Details:    details,
+			Suggestion: exampleContent.Suggestion,
+		}); err != nil {
+			return
+		}
+		os.Exit(1)
+	}
+}

cmd/terraform.go

@@ -18,6 +18,7 @@ var terraformCmd = &cobra.Command{
 	Short:              "Execute Terraform commands (e.g., plan, apply, destroy) using Atmos stack configurations",
 	Long:               `This command allows you to execute Terraform commands, such as plan, apply, and destroy, using Atmos stack configurations for consistent infrastructure management.`,
 	FParseErrWhitelist: struct{ UnknownFlags bool }{UnknownFlags: true},
+	Example:            `atmos terraform [sub-command] <component> -s <stack>`,
 	PostRunE: func(cmd *cobra.Command, args []string) error {
 		info := getConfigAndStacksInfo("terraform", cmd, args)
 		return hooks.RunE(cmd, args, &info)
@@ -50,6 +51,7 @@ func init() {
 	// https://github.com/spf13/cobra/issues/739
 	terraformCmd.DisableFlagParsing = true
 	terraformCmd.PersistentFlags().StringP("stack", "s", "", "atmos terraform <terraform_command> <component> -s <stack>")
+	terraformCmd.PersistentFlags().Bool("", false, doubleDashHint)
 	attachTerraformCommands(terraformCmd)
 	RootCmd.AddCommand(terraformCmd)
 }

cmd/workflow.go

@@ -34,7 +34,12 @@ func renderError(msg ErrorMessage) error {
 	}
 
 	termWriter := termwriter.NewResponsiveWriter(os.Stdout)
-	screenWidth := termWriter.(*termwriter.TerminalWriter).GetWidth()
+	var wr *termwriter.TerminalWriter
+	var ok bool
+	if wr, ok = termWriter.(*termwriter.TerminalWriter); !ok {
+		return fmt.Errorf("unsupported output")
+	}
+	screenWidth := wr.GetWidth()
 
 	if atmosConfig.Settings.Docs.MaxWidth > 0 {
 		screenWidth = uint(min(atmosConfig.Settings.Docs.MaxWidth, int(screenWidth)))

internal/tui/templates/base_template.go

@@ -46,7 +46,7 @@ func getSection(section HelpTemplateSections) string {
 	case SubCommandAliases:
 		return `{{if (isAliasesPresent .Commands)}}
 
-{{HeadingStyle "SubCommand Aliases:"}}
+{{HeadingStyle "Subcommand Aliases:"}}
 
 {{formatCommands .Commands "subcommandAliases"}}{{end}}`
 	case AvailableCommands:

internal/tui/templates/templater.go

@@ -169,14 +169,13 @@ func SetCustomUsageFunc(cmd *cobra.Command) error {
 		UsageTemplate: GenerateFromBaseTemplate([]HelpTemplateSections{
 			Usage,
 			Aliases,
-			Examples,
 			AvailableCommands,
 			NativeCommands,
 			SubCommandAliases,
 			Flags,
 			GlobalFlags,
 			AdditionalHelpTopics,
-			DoubleDashHelp,
+			Examples,
 			Footer,
 		}),
 	}

pkg/ui/markdown/renderer.go

@@ -91,7 +91,7 @@ func (r *Renderer) RenderError(title, details, suggestion string) (string, error
 
 	if suggestion != "" {
 		if strings.HasPrefix(suggestion, "http") {
-			content += fmt.Sprintf("For more information, refer to the **docs**\n%s\n", suggestion)
+			content += fmt.Sprintf("\nFor more information, refer to the [docs](%s)\n", suggestion)
 		} else {
 			content += suggestion
 		}