Improve Atmos help

[samtholiya]

what

We would be fixing the following UX issues with help in this pr:

• atmos about non-existent should show usage:
  

• Double dash in flags of atmos terraform --help and examples rendering using markdown if available.
  

• Fixed atmos workflow --file example.yaml bug for markdown. Now it also exits with exit code 1.
  

• Updated Default error logger with markdown support.
  

• Added custom alias help support so that alias in config should also be displayed in help.
  

• Updated the workflow name invalid UI
  

• Invalid custom command config now shows better help
  

• Invalid flag usage added
  

why

• Outputting markdown in help descriptions makes it easier to visually parse
• Markdown stylesheet keeps formatting consistent, without each developer needing to know the style guide
• Changed the way error that exit are displayed, to show more helpful information and usage examples, also formatted in markdown
• Aliases were not shown in help, making their discoverability difficult

references

• DEV-2950
• DEV-2690

Summary by CodeRabbit

• Enhanced CLI Experience

  • Error messages, usage, and help outputs across multiple Atmos commands are now displayed using a clear Markdown format. Users receive more descriptive feedback for invalid commands or flags and improved prompts during execution.
  • Specific error messages have been improved to include context and suggestions for available workflows and commands, particularly when workflows are not found or when invalid commands are issued.
  • New error messages provide clear guidance when invalid or non-existent commands are invoked, listing valid options for user convenience.
  • The command atmos terraform now specifies required subcommands and provides usage examples when invoked incorrectly.

• Updated Documentation

  • Command usage examples and help texts for key functionality (such as for Atmos “about,” “terraform,” “workflow,” “helmfile,” and “atlantis” commands) have been refined, offering clearer guidance and structured instructions for end-user workflows.
  • New sections have been added to documentation, detailing how to apply changes to Terraform components and providing examples for using workflow commands effectively.
  • Additional help messages have been introduced for commands like atmos validate editorconfig, enhancing user understanding of available flags and options.
  • Documentation updates reflect the latest versions of Atmos and Geodesic tools, ensuring users have the most current information for their workflows.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

tests/test-cases/help-and-usage.yaml (2)

439-489: LGTM! New test cases enhance coverage.

The new test cases for atmos about and atmos version commands improve the test coverage for error handling and help output. The test in the fixtures/scenarios/subcommand-alias directory is particularly valuable for verifying custom alias functionality.

However, consider adding test cases for the following scenarios to make the test suite more comprehensive:

1. Invalid alias configurations
2. Multiple aliases for the same command
3. Nested alias commands

---

371-378: Consider standardizing stdout/stderr expectations.

While most test cases use the diff field for output validation, this test case uses explicit stdout and stderr fields. Consider standardizing the approach across all test cases.

-      stdout:
-        - "Flags:"
-        - "--affected-only"
-        - "--config-template"
-      stderr:
-        - "^$"
+      diff:
+        - "──────────────────────────────────────────────────────────────"
+        - "Update available!"
+        - "Atmos Releases:"
+        - "Install Atmos:"
+        - "Flags:"
+        - "--affected-only"
+        - "--config-template"

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8354b03 and 64424ee.

📒 Files selected for processing (1)

• tests/test-cases/help-and-usage.yaml (15 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (3)

• GitHub Check: Build (windows-latest, windows)
• GitHub Check: website-deploy-preview
• GitHub Check: Summary

🔇 Additional comments (2)

tests/test-cases/help-and-usage.yaml (2)

4-4: LGTM! Consistent addition of snapshot testing.

The addition of snapshot: true across test cases is a solid improvement. This will help catch unintended changes in CLI output.

Also applies to: 14-14, 24-24, 40-40, 56-56, 73-73, 90-90, 101-101, 113-113, 125-125, 135-135, 145-145, 161-161, 188-188, 199-199, 216-216, 233-233, 243-243, 259-259, 276-276, 287-287, 304-304, 321-321, 338-338, 356-356

---

32-37: Standardize help output expectations.

The standardized diff expectations for help output will ensure consistent formatting and update notifications across all commands.

Also applies to: 48-53, 65-70, 82-87, 153-158, 169-174, 208-213, 225-230, 251-256, 267-272, 296-301, 313-318, 330-335, 348-353, 366-371, 403-408, 422-427

[github-actions]

These changes were released in v1.162.0.