Fix help text rendering and update Atmos description

[osterman]

what

• Fix command descriptions in help to render markdown properly and respect text width constraints
• Use correct commandDesc style for command descriptions instead of commandName style
• Update Atmos short and long descriptions to "framework for orchestrating and operating infrastructure workflows across multiple cloud and DevOps toolchains"

why

• Command descriptions were rendering with incorrect styling (bold primary color instead of secondary text color) and markdown was being processed incorrectly due to double word-wrapping
• The descriptions now match the rendering approach used by flag descriptions, ensuring consistent and proper markdown rendering
• Updated descriptions better reflect what Atmos is and how it works

references

• Related to help text rendering improvements

Summary by CodeRabbit

• Documentation

  • Updated Atmos product description in README and help text to reflect its positioning as a framework for orchestrating and operating infrastructure workflows across multiple cloud and DevOps toolchains.

• New Features

  • Enhanced help output rendering with markdown support for improved formatting and display of command descriptions.

• Tests

  • Added test coverage for markdown-aware help rendering and updated existing tests to align with new rendering capabilities.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues found.

Scanned Files

None

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes integrate markdown rendering into the CLI help system by adding a renderer parameter to the command formatting function. The Atmos framework description is also updated across README, root command metadata, and help snapshots to reflect a refined positioning.

Changes

Cohort / File(s)	Summary
Markdown rendering integration cmd/help_template.go, cmd/help_template_test.go	Added markdown renderer parameter to formatCommandLine() function. Descriptions now flow through optional markdown rendering before output. Extended tests cover markdown formatting scenarios and atmospheric configuration paths.
Description and metadata updates README.yaml, cmd/root.go	Updated Atmos framework description to: "a framework for orchestrating and operating infrastructure workflows across multiple cloud and DevOps toolchains." Applied consistently across README and root command metadata.
Help snapshot updates tests/snapshots/TestCLICommands_atmos_--help*	Updated help output snapshots to reflect the revised Atmos framework description.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• cmd/help_template.go: Review the markdown renderer integration into the rendering pipeline and ensure proper null-handling for the optional parameter.
• cmd/help_template_test.go: Validate test coverage breadth for markdown rendering scenarios, particularly with and without renderer availability.
• Snapshots: Verify description consistency across all help output variations.

Suggested reviewers

• osterman

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main changes: fixing help text rendering for markdown and updating the Atmos product description.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch osterman/list-help-markdown-color

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 7ef5183 and 31e5c0c.

📒 Files selected for processing (6)

• README.yaml (1 hunks)
• cmd/help_template.go (3 hunks)
• cmd/help_template_test.go (3 hunks)
• cmd/root.go (1 hunks)
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden (1 hunks)
• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden (1 hunks)

🧰 Additional context used

📓 Path-based instructions (4)

cmd/**/*.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

cmd/**/*.go: Use Cobra's recommended command structure with a root command and subcommands, implementing each command in a separate file under cmd/ directory
Provide comprehensive help text for all commands and flags, include examples in command help, and follow Go's documentation conventions in Cobra command definitions
Provide meaningful feedback to users and include progress indicators for long-running operations in CLI commands

cmd/**/*.go: Commands MUST use flags.NewStandardParser() for command-specific flags; NEVER call viper.BindEnv() or viper.BindPFlag() directly (Forbidigo enforces this); see cmd/version/version.go for reference
Embed CLI examples from cmd/markdown/*_usage.md using //go:embed; render with utils.PrintfMarkdown()

Files:

• cmd/help_template_test.go
• cmd/help_template.go
• cmd/root.go

**/*.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*.go: Use Viper for managing configuration, environment variables, and flags in CLI commands
Use interfaces for external dependencies to facilitate mocking and consider using testify/mock for creating mock implementations
All code must pass golangci-lint checks
Follow Go's error handling idioms: use meaningful error messages, wrap errors with context using fmt.Errorf("context: %w", err), and consider using custom error types for domain-specific errors
Follow standard Go coding style: use gofmt and goimports to format code, prefer short descriptive variable names, use kebab-case for command-line flags, and snake_case for environment variables
Document all exported functions, types, and methods following Go's documentation conventions
Document complex logic with inline comments in Go code
Support configuration via files, environment variables, and flags following the precedence order: flags > environment variables > config file > defaults
Provide clear error messages to users, include troubleshooting hints when appropriate, and log detailed errors for debugging

**/*.go: NEVER use fmt.Fprintf(os.Stdout/Stderr) or fmt.Println(); use data.* or ui.* functions instead
All comments must end with periods (enforced by godot linter)
Organize imports in three groups separated by blank lines, sorted alphabetically: 1) Go stdlib, 2) 3rd-party (NOT cloudposse/atmos), 3) Atmos packages; maintain aliases: cfg, log, u, errUtils
Add defer perf.Track(atmosConfig, "pkg.FuncName")() + blank line to all public functions for performance tracking; use nil if no atmosConfig param
All errors MUST be wrapped using static errors defined in errors/errors.go; use errors.Join for combining multiple errors; use fmt.Errorf with %w for adding string context; use error builder for complex errors; use errors.Is() for error checking; NEVER use dynamic errors directly
Use go.uber.org/mock/mockgen with //go:generate directives for mock generation; never create manual mocks
Keep files small...

Files:

• cmd/help_template_test.go
• cmd/help_template.go
• cmd/root.go

**/*_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*_test.go: Every new feature must include comprehensive unit tests targeting >80% code coverage for all packages
Use table-driven tests for testing multiple scenarios in Go
Include integration tests for command flows and test CLI end-to-end when possible with test fixtures

**/*_test.go: Prefer unit tests with mocks over integration tests; use interfaces + dependency injection for testability; generate mocks with go.uber.org/mock/mockgen; use table-driven tests; target >80% coverage
Test behavior, not implementation; never test stub functions; avoid tautological tests; make code testable via DI; no coverage theater; remove always-skipped tests; use errors.Is() for error checking

Files:

• cmd/help_template_test.go

cmd/**/*_test.go

📄 CodeRabbit inference engine (CLAUDE.md)

ALWAYS use cmd.NewTestKit(t) for cmd tests to auto-clean RootCmd state (flags, args)

Files:

• cmd/help_template_test.go

🧠 Learnings (50)

📓 Common learnings

Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: docs/prd/tool-dependencies-integration.md:58-64
Timestamp: 2025-12-13T06:07:37.766Z
Learning: cloudposse/atmos: For PRD docs (docs/prd/*.md), markdownlint issues like MD040/MD010/MD034 can be handled in a separate documentation cleanup commit and should not block the current PR.

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 955
File: tests/snapshots/TestCLICommands_atmos_validate_editorconfig_--help.stdout.golden:0-0
Timestamp: 2025-01-19T15:49:15.593Z
Learning: In future commits, the help text for Atmos CLI commands should be limited to only show component and stack parameters for commands that actually use them. This applies to the example usage section in command help text.

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: cmd/markdown/atmos_toolchain_aliases.md:2-4
Timestamp: 2025-09-13T16:39:20.007Z
Learning: In the cloudposse/atmos repository, CLI documentation files in cmd/markdown/ follow a specific format that uses " $ atmos command" (with leading space and dollar sign prompt) in code blocks. This is the established project convention and should not be changed to comply with standard markdownlint rules MD040 and MD014.

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1068
File: tests/snapshots/TestCLICommands_atmos_terraform_help.stdout.golden:59-64
Timestamp: 2025-02-18T13:13:11.497Z
Learning: For Atmos CLI help text, angle brackets in command examples and flag descriptions should be escaped using HTML entities (e.g., `<component>`) rather than converted to backticks or other markdown formatting.

Learnt from: osterman
Repo: cloudposse/atmos PR: 1533
File: pkg/config/load.go:585-637
Timestamp: 2025-09-27T20:50:20.564Z
Learning: In the cloudposse/atmos repository, command merging prioritizes precedence over display ordering. Help commands are displayed lexicographically regardless of internal array order, so the mergeCommandArrays function focuses on ensuring the correct precedence chain (top-level file wins) rather than maintaining specific display order.

Learnt from: Listener430
Repo: cloudposse/atmos PR: 934
File: tests/fixtures/scenarios/docs-generate/README.md.gotmpl:99-118
Timestamp: 2025-01-25T03:51:57.689Z
Learning: For the cloudposse/atmos repository, changes to template contents should be handled in dedicated PRs and are typically considered out of scope for PRs focused on other objectives.

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to README.md : Update README.md with new commands and features

Learnt from: osterman
Repo: cloudposse/atmos PR: 1498
File: website/src/components/Screengrabs/atmos-terraform-metadata--help.html:25-55
Timestamp: 2025-10-07T00:25:16.333Z
Learning: In Atmos CLI, subcommands inherit flags from their parent commands via Cobra's command inheritance. For example, `atmos terraform metadata --help` shows `--affected` and related flags inherited from the parent `terraform` command (defined in cmd/terraform.go), even though the metadata subcommand doesn't explicitly define these flags. This is expected Cobra behavior and auto-generated help screengrabs accurately reflect this inheritance.

Learnt from: osterman
Repo: cloudposse/atmos PR: 1498
File: website/src/components/Screengrabs/atmos-completion--help.html:2-7
Timestamp: 2025-10-14T01:54:48.410Z
Learning: Screengrab HTML files in website/src/components/Screengrabs/ are generated from actual Atmos CLI output converted to HTML. The ANSI-art headers and formatting in these files are intentional and reflect the real CLI user experience, so they should not be suggested for removal or modification.

Learnt from: osterman
Repo: cloudposse/atmos PR: 729
File: internal/exec/help.go:48-51
Timestamp: 2024-10-27T16:59:26.187Z
Learning: In the Atmos CLI help messages, when providing examples that include the version number, use the actual version variable (e.g., `version.Version`) instead of placeholders like `<version>`.

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-16T18:20:55.614Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : All CLI commands/flags need Docusaurus documentation in website/docs/cli/commands/ with specific structure: frontmatter, Intro component, Screengrab component, Usage section, Arguments/Flags using <dl><dt>/<dd>, and Examples section

📚 Learning: 2025-09-10T21:17:55.273Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: toolchain/http_client_test.go:3-10
Timestamp: 2025-09-10T21:17:55.273Z
Learning: In the cloudposse/atmos repository, imports should never be changed as per samtholiya's coding guidelines.

Applied to files:

• README.yaml
• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden

📚 Learning: 2025-01-25T03:51:57.689Z

Learnt from: Listener430
Repo: cloudposse/atmos PR: 934
File: tests/fixtures/scenarios/docs-generate/README.md.gotmpl:99-118
Timestamp: 2025-01-25T03:51:57.689Z
Learning: For the cloudposse/atmos repository, changes to template contents should be handled in dedicated PRs and are typically considered out of scope for PRs focused on other objectives.

Applied to files:

• README.yaml

📚 Learning: 2025-11-01T20:24:29.557Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1714
File: NOTICE:0-0
Timestamp: 2025-11-01T20:24:29.557Z
Learning: In the cloudposse/atmos repository, the NOTICE file is programmatically generated and should not be manually edited. Issues with dependency license URLs in NOTICE will be resolved when upstream package metadata is corrected.

Applied to files:

• README.yaml

📚 Learning: 2025-03-18T12:26:25.329Z

Learnt from: Listener430
Repo: cloudposse/atmos PR: 1149
File: tests/snapshots/TestCLICommands_atmos_vendor_pull_ssh.stderr.golden:7-7
Timestamp: 2025-03-18T12:26:25.329Z
Learning: In the Atmos project, typos or inconsistencies in test snapshot files (such as "terrafrom" instead of "terraform") may be intentional as they capture the exact output of commands and should not be flagged as issues requiring correction.

Applied to files:

• README.yaml
• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2024-11-25T17:17:15.703Z

Learnt from: RoseSecurity
Repo: cloudposse/atmos PR: 797
File: pkg/list/atmos.yaml:213-214
Timestamp: 2024-11-25T17:17:15.703Z
Learning: The file `pkg/list/atmos.yaml` is primarily intended for testing purposes.

Applied to files:

• README.yaml
• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2025-09-13T16:39:20.007Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: cmd/markdown/atmos_toolchain_aliases.md:2-4
Timestamp: 2025-09-13T16:39:20.007Z
Learning: In the cloudposse/atmos repository, CLI documentation files in cmd/markdown/ follow a specific format that uses " $ atmos command" (with leading space and dollar sign prompt) in code blocks. This is the established project convention and should not be changed to comply with standard markdownlint rules MD040 and MD014.

Applied to files:

• README.yaml
• cmd/help_template_test.go
• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden
• cmd/help_template.go

📚 Learning: 2025-12-13T06:07:37.766Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: docs/prd/tool-dependencies-integration.md:58-64
Timestamp: 2025-12-13T06:07:37.766Z
Learning: cloudposse/atmos: For PRD docs (docs/prd/*.md), markdownlint issues like MD040/MD010/MD034 can be handled in a separate documentation cleanup commit and should not block the current PR.

Applied to files:

• README.yaml

📚 Learning: 2024-12-01T00:33:20.298Z

Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: examples/tests/stacks/catalog/terraform/template-functions-test2/defaults.yaml:28-32
Timestamp: 2024-12-01T00:33:20.298Z
Learning: In `examples/tests/stacks/catalog/terraform/template-functions-test2/defaults.yaml`, `!exec atmos terraform output` is used in examples to demonstrate its usage, even though `!terraform.output` is the recommended approach according to the documentation.

Applied to files:

• README.yaml

📚 Learning: 2025-10-14T01:54:48.410Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1498
File: website/src/components/Screengrabs/atmos-completion--help.html:2-7
Timestamp: 2025-10-14T01:54:48.410Z
Learning: Screengrab HTML files in website/src/components/Screengrabs/ are generated from actual Atmos CLI output converted to HTML. The ANSI-art headers and formatting in these files are intentional and reflect the real CLI user experience, so they should not be suggested for removal or modification.

Applied to files:

• README.yaml

📚 Learning: 2025-12-16T18:20:55.614Z

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-16T18:20:55.614Z
Learning: Applies to cmd/**/*.go : Embed CLI examples from cmd/markdown/*_usage.md using //go:embed; render with utils.PrintfMarkdown()

Applied to files:

• cmd/help_template_test.go
• cmd/help_template.go

📚 Learning: 2025-11-24T17:35:37.209Z

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to cmd/**/*.go : Provide comprehensive help text for all commands and flags, include examples in command help, and follow Go's documentation conventions in Cobra command definitions

Applied to files:

• cmd/help_template_test.go
• cmd/help_template.go
• cmd/root.go

📚 Learning: 2024-12-07T16:16:13.038Z

Learnt from: Listener430
Repo: cloudposse/atmos PR: 825
File: internal/exec/helmfile_generate_varfile.go:28-31
Timestamp: 2024-12-07T16:16:13.038Z
Learning: In `internal/exec/helmfile_generate_varfile.go`, the `--help` command (`./atmos helmfile generate varfile --help`) works correctly without requiring stack configurations, and the only change needed was to make `ProcessCommandLineArgs` exportable by capitalizing its name.

Applied to files:

• cmd/help_template_test.go
• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden
• cmd/help_template.go

📚 Learning: 2025-06-02T14:12:02.710Z

Learnt from: milldr
Repo: cloudposse/atmos PR: 1229
File: internal/exec/workflow_test.go:0-0
Timestamp: 2025-06-02T14:12:02.710Z
Learning: In the atmos codebase, workflow error handling was refactored to use `PrintErrorMarkdown` followed by returning the error instead of `PrintErrorMarkdownAndExit`. This pattern allows proper error testing without the function terminating the process with `os.Exit`, enabling unit tests to assert on error conditions.

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2025-11-24T17:35:37.209Z

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to **/*_test.go : Include integration tests for command flows and test CLI end-to-end when possible with test fixtures

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2025-01-07T20:38:09.618Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 896
File: cmd/editor_config.go:37-40
Timestamp: 2025-01-07T20:38:09.618Z
Learning: Error handling suggestion for `cmd.Help()` in `cmd/editor_config.go` was deferred as the code is planned for future modifications.

Applied to files:

• cmd/help_template_test.go
• cmd/help_template.go

📚 Learning: 2025-06-02T14:12:02.710Z

Learnt from: milldr
Repo: cloudposse/atmos PR: 1229
File: internal/exec/workflow_test.go:0-0
Timestamp: 2025-06-02T14:12:02.710Z
Learning: In the atmos codebase, workflow error handling was refactored to use `PrintErrorMarkdown` followed by returning specific error variables (like `ErrWorkflowNoSteps`, `ErrInvalidFromStep`, `ErrInvalidWorkflowStepType`, `ErrWorkflowStepFailed`) instead of `PrintErrorMarkdownAndExit`. This pattern allows proper error testing without the function terminating the process with `os.Exit`, enabling unit tests to assert on error conditions while maintaining excellent user-facing error formatting.

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2025-01-09T22:27:25.538Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 914
File: cmd/validate_stacks.go:20-23
Timestamp: 2025-01-09T22:27:25.538Z
Learning: The validate commands in Atmos can have different help handling implementations. Specifically, validate_component.go and validate_stacks.go are designed to handle help requests differently, with validate_stacks.go including positional argument checks while validate_component.go does not.

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2025-12-16T18:20:55.614Z

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-16T18:20:55.614Z
Learning: Applies to **/*_test.go : Test behavior, not implementation; never test stub functions; avoid tautological tests; make code testable via DI; no coverage theater; remove always-skipped tests; use errors.Is() for error checking

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2025-09-13T18:06:07.674Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: toolchain/list.go:39-42
Timestamp: 2025-09-13T18:06:07.674Z
Learning: In the cloudposse/atmos repository, for UI messages in the toolchain package, use utils.PrintfMessageToTUI instead of log.Error or fmt.Fprintln(os.Stderr, ...). Import pkg/utils with alias "u" to follow the established pattern.

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2025-11-24T17:35:37.209Z

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to **/*_test.go : Use table-driven tests for testing multiple scenarios in Go

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2024-11-01T15:44:12.617Z

Learnt from: RoseSecurity
Repo: cloudposse/atmos PR: 757
File: cmd/docs.go:42-59
Timestamp: 2024-11-01T15:44:12.617Z
Learning: In `cmd/docs.go`, when implementing width detection for the `docsCmd` command, it's acceptable to keep the code inline without extracting it into a separate function, as per the user's preference for compact readability and maintainability in Go code.

Applied to files:

• cmd/help_template_test.go
• cmd/help_template.go

📚 Learning: 2024-11-01T14:45:32.417Z

Learnt from: RoseSecurity
Repo: cloudposse/atmos PR: 757
File: cmd/docs.go:52-54
Timestamp: 2024-11-01T14:45:32.417Z
Learning: In `cmd/docs.go`, capping the terminal width at 120 columns is considered acceptable and preferred after testing.

Applied to files:

• cmd/help_template_test.go
• cmd/help_template.go

📚 Learning: 2025-11-24T17:35:37.209Z

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to cmd/**/*.go : Provide meaningful feedback to users and include progress indicators for long-running operations in CLI commands

Applied to files:

• cmd/help_template_test.go
• cmd/help_template.go

📚 Learning: 2025-12-16T18:20:55.614Z

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-16T18:20:55.614Z
Learning: Applies to **/*.go : NEVER use fmt.Fprintf(os.Stdout/Stderr) or fmt.Println(); use data.* or ui.* functions instead

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2025-02-03T06:00:11.419Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 959
File: cmd/describe_config.go:20-20
Timestamp: 2025-02-03T06:00:11.419Z
Learning: Commands should use `PrintErrorMarkdownAndExit` with empty title and suggestion (`"", err, ""`) for general error handling. Specific titles like "Invalid Usage" or "File Not Found" should only be used for validation or specific error scenarios.

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2025-02-03T06:00:11.419Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 959
File: cmd/describe_config.go:20-20
Timestamp: 2025-02-03T06:00:11.419Z
Learning: The `describe config` command should use `PrintErrorMarkdownAndExit` with empty title and suggestion for consistency with other commands.

Applied to files:

• cmd/help_template_test.go
• cmd/help_template.go

📚 Learning: 2025-10-07T00:25:16.333Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1498
File: website/src/components/Screengrabs/atmos-terraform-metadata--help.html:25-55
Timestamp: 2025-10-07T00:25:16.333Z
Learning: In Atmos CLI, subcommands inherit flags from their parent commands via Cobra's command inheritance. For example, `atmos terraform metadata --help` shows `--affected` and related flags inherited from the parent `terraform` command (defined in cmd/terraform.go), even though the metadata subcommand doesn't explicitly define these flags. This is expected Cobra behavior and auto-generated help screengrabs accurately reflect this inheritance.

Applied to files:

• cmd/help_template_test.go
• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden
• cmd/root.go

📚 Learning: 2025-12-10T18:32:43.260Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1808
File: cmd/terraform/backend/backend_delete_test.go:9-23
Timestamp: 2025-12-10T18:32:43.260Z
Learning: In cmd subpackages, tests should avoid using NewTestKit(t) unless tests actually interact with RootCmd (e.g., execute commands via RootCmd or modify RootCmd state). For structural tests that only verify command structure/flags without touching RootCmd, TestKit cleanup is unnecessary.

Applied to files:

• cmd/help_template_test.go

📚 Learning: 2025-12-13T04:37:40.435Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: cmd/toolchain/get.go:23-40
Timestamp: 2025-12-13T04:37:40.435Z
Learning: In Go CLI command files using Cobra, constrain the subcommand to accept at most one positional argument (MaximumNArgs(1)) so it supports both listing all items (zero args) and fetching a specific item (one arg). Define and parse flags with a standard parser (e.g., flags.NewStandardParser()) and avoid binding flags to Viper (no viper.BindEnv/BindPFlag). This promotes explicit argument handling and predictable flag behavior across command files.

Applied to files:

• cmd/help_template_test.go
• cmd/help_template.go
• cmd/root.go

📚 Learning: 2025-01-19T15:49:15.593Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 955
File: tests/snapshots/TestCLICommands_atmos_validate_editorconfig_--help.stdout.golden:0-0
Timestamp: 2025-01-19T15:49:15.593Z
Learning: In future commits, the help text for Atmos CLI commands should be limited to only show component and stack parameters for commands that actually use them. This applies to the example usage section in command help text.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2025-02-18T13:13:11.497Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1068
File: tests/snapshots/TestCLICommands_atmos_terraform_help.stdout.golden:59-64
Timestamp: 2025-02-18T13:13:11.497Z
Learning: For Atmos CLI help text, angle brackets in command examples and flag descriptions should be escaped using HTML entities (e.g., `<component>`) rather than converted to backticks or other markdown formatting.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2025-02-14T23:12:38.030Z

Learnt from: Listener430
Repo: cloudposse/atmos PR: 1061
File: tests/snapshots/TestCLICommands_atmos_vendor_pull_ssh.stderr.golden:8-8
Timestamp: 2025-02-14T23:12:38.030Z
Learning: Test snapshots in the Atmos project, particularly for dry run scenarios, may be updated during the development process, and temporary inconsistencies in their content should not be flagged as issues.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden

📚 Learning: 2025-09-27T20:50:20.564Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1533
File: pkg/config/load.go:585-637
Timestamp: 2025-09-27T20:50:20.564Z
Learning: In the cloudposse/atmos repository, command merging prioritizes precedence over display ordering. Help commands are displayed lexicographically regardless of internal array order, so the mergeCommandArrays function focuses on ensuring the correct precedence chain (top-level file wins) rather than maintaining specific display order.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2025-09-05T14:57:37.360Z

Learnt from: RoseSecurity
Repo: cloudposse/atmos PR: 1448
File: cmd/ansible.go:26-28
Timestamp: 2025-09-05T14:57:37.360Z
Learning: The Atmos codebase uses a consistent pattern for commands that delegate to external tools: `PersistentFlags().Bool("", false, doubleDashHint)` where doubleDashHint provides help text about using double dashes to separate Atmos options from native command arguments. This pattern is used across terraform, packer, helmfile, atlantis, aws, and ansible commands.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden
• cmd/root.go

📚 Learning: 2025-11-07T14:52:55.217Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1761
File: docs/prd/claude-agent-architecture.md:331-439
Timestamp: 2025-11-07T14:52:55.217Z
Learning: In the cloudposse/atmos repository, Claude agents are used as interactive tools, not in automated/headless CI/CD contexts. Agent documentation and patterns should assume synchronous human interaction.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2025-11-11T03:47:59.576Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: toolchain/which_test.go:166-223
Timestamp: 2025-11-11T03:47:59.576Z
Learning: In the cloudposse/atmos repo, tests that manipulate environment variables should use testing.T.Setenv for automatic setup/teardown instead of os.Setenv/Unsetenv.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2025-09-08T01:25:44.958Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: The atmos toolchain has been updated to follow XDG Base Directory Specification with helper functions GetXDGCacheDir() and GetXDGTempCacheDir() in toolchain/xdg_cache.go, using XDG_CACHE_HOME when set and falling back to ~/.cache/atmos-toolchain, making it consistent with atmos core's XDG compliance.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2025-01-30T19:30:59.120Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 959
File: cmd/workflow.go:74-74
Timestamp: 2025-01-30T19:30:59.120Z
Learning: Error handling for `cmd.Usage()` is not required in the Atmos CLI codebase, as confirmed by the maintainer.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden
• cmd/root.go

📚 Learning: 2025-02-06T13:38:07.216Z

Learnt from: Listener430
Repo: cloudposse/atmos PR: 984
File: internal/exec/copy_glob.go:0-0
Timestamp: 2025-02-06T13:38:07.216Z
Learning: The `u.LogTrace` function in the `cloudposse/atmos` repository accepts `atmosConfig` as its first parameter, followed by the message string.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2024-12-11T18:40:12.808Z

Learnt from: Listener430
Repo: cloudposse/atmos PR: 844
File: cmd/helmfile.go:37-37
Timestamp: 2024-12-11T18:40:12.808Z
Learning: In the atmos project, `cliConfig` is initialized within the `cmd` package in `root.go` and can be used in other command files.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden
• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden
• cmd/root.go

📚 Learning: 2024-10-27T16:59:26.187Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 729
File: internal/exec/help.go:48-51
Timestamp: 2024-10-27T16:59:26.187Z
Learning: In the Atmos CLI help messages, when providing examples that include the version number, use the actual version variable (e.g., `version.Version`) instead of placeholders like `<version>`.

Applied to files:

• tests/snapshots/TestCLICommands_atmos_--help.stdout.golden

📚 Learning: 2025-06-23T02:14:30.937Z

Learnt from: aknysh
Repo: cloudposse/atmos PR: 1327
File: cmd/terraform.go:111-117
Timestamp: 2025-06-23T02:14:30.937Z
Learning: In cmd/terraform.go, flags for the DescribeAffected function are added dynamically at runtime when info.Affected is true. This is intentional to avoid exposing internal flags like "file", "format", "verbose", "include-spacelift-admin-stacks", "include-settings", and "upload" in the terraform command interface, while still providing them for the shared DescribeAffected function used by both `atmos describe affected` and `atmos terraform apply --affected`.

Applied to files:

• cmd/help_template.go

📚 Learning: 2025-12-16T18:20:55.614Z

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-16T18:20:55.614Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : All CLI commands/flags need Docusaurus documentation in website/docs/cli/commands/ with specific structure: frontmatter, Intro component, Screengrab component, Usage section, Arguments/Flags using <dl><dt>/<dd>, and Examples section

Applied to files:

• cmd/help_template.go

📚 Learning: 2025-11-24T17:35:37.209Z

Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to cmd/**/*.go : Use Cobra's recommended command structure with a root command and subcommands, implementing each command in a separate file under `cmd/` directory

Applied to files:

• cmd/root.go

📚 Learning: 2024-12-11T18:46:02.483Z

Learnt from: Listener430
Repo: cloudposse/atmos PR: 844
File: cmd/terraform.go:39-39
Timestamp: 2024-12-11T18:46:02.483Z
Learning: `cliConfig` is initialized in `cmd/root.go` and can be used across the `cmd` package.

Applied to files:

• cmd/root.go

📚 Learning: 2025-12-13T04:37:25.223Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: cmd/root.go:0-0
Timestamp: 2025-12-13T04:37:25.223Z
Learning: In Atmos cmd/root.go Execute(), after cfg.InitCliConfig, we must call both toolchainCmd.SetAtmosConfig(&atmosConfig) and toolchain.SetAtmosConfig(&atmosConfig) so the CLI wrapper and the toolchain package receive configuration; missing either can cause nil-pointer panics in toolchain path resolution.

Applied to files:

• cmd/root.go

📚 Learning: 2025-09-07T18:07:00.549Z

Learnt from: Benbentwo
Repo: cloudposse/atmos PR: 1452
File: cmd/auth_login.go:43-44
Timestamp: 2025-09-07T18:07:00.549Z
Learning: In the atmos project, the identity flag is defined as a persistent flag on the auth root command (cmd/auth.go), making it available to all auth subcommands without needing to be redefined in each individual subcommand.

Applied to files:

• cmd/root.go

📚 Learning: 2025-01-18T15:15:41.645Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 914
File: cmd/terraform.go:37-46
Timestamp: 2025-01-18T15:15:41.645Z
Learning: In the atmos CLI, error handling is intentionally structured to use LogErrorAndExit for consistent error display, avoiding Cobra's default error handling to prevent duplicate error messages.

Applied to files:

• cmd/root.go

📚 Learning: 2024-10-20T13:12:46.499Z

Learnt from: haitham911
Repo: cloudposse/atmos PR: 736
File: pkg/config/const.go:6-6
Timestamp: 2024-10-20T13:12:46.499Z
Learning: In `cmd/cmd_utils.go`, it's acceptable to have hardcoded references to `atmos.yaml` in logs, and it's not necessary to update them to use the `CliConfigFileName` constant.

Applied to files:

• cmd/root.go

⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Acceptance Tests (macos)
• GitHub Check: Acceptance Tests (windows)
• GitHub Check: Summary

🔇 Additional comments (10)

cmd/root.go (1)

299-300: LGTM!

The updated Short and Long descriptions align well with the PR objectives. The new framing clearly communicates Atmos's purpose as an infrastructure orchestration framework.

README.yaml (1)

42-43: LGTM!

The README description now aligns with the CLI help text. Consistency across documentation and CLI is good practice.

tests/snapshots/TestCLICommands_atmos_--help.stdout.golden (1)

4-5: LGTM!

Snapshot correctly reflects the updated Atmos description. The word-wrapping across two lines is expected terminal behavior.

tests/snapshots/TestCLICommands_atmos_--help_config_aliases_section.stdout.golden (1)

4-5: LGTM!

Snapshot matches the updated description. Consistent with other help output changes.

cmd/help_template.go (2)

521-573: LGTM!

The updated formatCommandLine properly integrates markdown rendering:

• Accepts optional mdRenderer parameter with nil-safe usage.
• Wraps plain text first, then applies markdown rendering (matching flag description approach).
• Uses commandDesc style consistently for all description lines, fixing the styling issue.

---

588-599: LGTM!

Good graceful degradation pattern. If markdown renderer creation fails, the code falls back to plain text rendering. This matches the approach used in flag rendering.

cmd/help_template_test.go (4)

13-15: LGTM!

Import properly placed in the Atmos packages group.

---

1063-1063: LGTM!

Passing nil for the markdown renderer is appropriate here since this test validates basic formatting without markdown processing.

---

1236-1300: Solid test coverage for the markdown renderer integration.

Table-driven structure is consistent with the codebase. Worth noting: the assertions verify token presence but not markdown transformation (e.g., that backticks are stripped). This is reasonable to avoid brittleness with terminal-specific rendering output.

---

1302-1366: Good coverage for the atmosConfig-triggered markdown path.

Follows the same pattern as TestPrintAvailableCommands which aids maintainability. The context setup with atmosConfig properly exercises the markdown renderer creation branch.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Review failed

The head commit changed during the review from 1e38c2b to 62a1653.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch osterman/list-help-markdown-color

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 90.90909% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 73.04%. Comparing base (7ef5183) to head (31e5c0c).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/help_template.go	90.90%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1875      +/-   ##
==========================================
+ Coverage   73.03%   73.04%   +0.01%     
==========================================
  Files         606      606              
  Lines       56329    56336       +7     
==========================================
+ Hits        41138    41152      +14     
+ Misses      12280    12274       -6     
+ Partials     2911     2910       -1     

Flag	Coverage Δ
unittests	73.04% <90.90%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
cmd/root.go	63.80% <ø> (ø)
cmd/help_template.go	68.07% <90.90%> (+0.53%)	⬆️

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

These changes were released in v1.202.0-rc.4.

[github-actions]

These changes were released in v1.203.0-test.1.