Repository navigation
docs: convert CLI command documentation from tables to definition lists - #1505
Merged
Merged
Conversation
## Summary - Convert 21 documentation files from markdown tables to HTML definition lists - Update flags and arguments sections to use <dl>, <dt>, <dd> tags - Maintain consistency with documentation standards ## Changes - Replace markdown table syntax with semantic HTML definition lists - Preserve all original content including descriptions, links, and formatting - Add proper required/optional indicators using <em> tags - Format aliases consistently using the pattern: `--flag` / `-f` ## Files Updated - 21 CLI command documentation files across multiple subdirectories - Converted 26 total tables (17 flags, 8 arguments, 1 exit codes) - All formatting, links, and descriptions preserved without abbreviation This improves documentation consistency and follows the project's documentation guidelines for using definition lists instead of tables for flags and arguments.
Erik Osterman (Cloud Posse) (osterman)
requested a review
from a team
as a code owner
September 24, 2025 03:00
Contributor
📝 WalkthroughWalkthroughDocumentation in website/docs/cli/commands was reformatted: Arguments and Flags tables were replaced with HTML definition lists (
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests
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. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1505 +/- ##
==========================================
+ Coverage 56.90% 56.98% +0.07%
==========================================
Files 284 284
Lines 30286 30286
==========================================
+ Hits 17235 17259 +24
+ Misses 11225 11199 -26
- Partials 1826 1828 +2
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Erik Osterman (Cloud Posse) (osterman)
added
the
no-release
Per review feedback, Exit Codes should remain as a table since they are reference values rather than flags or arguments.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (10)
website/docs/cli/commands/atlantis/atlantis-generate-repo-config.mdx (1)
67-106: Docs DL conversion looks good; consider replacing
with paragraphs for accessibility.The new
structure is clear. Minor: long
- entries (e.g., --clone-target-ref) would be more accessible/readable using paragraphs instead of multiple
tags. Also consider stating defaults where applicable (e.g., whether --affected-only defaults to false) for parity with CLI help.website/docs/cli/commands/pro/pro-unlock.mdx (1)
43-49: Standardize alias formatting to match other command docs.Elsewhere aliases are shown as
--flag/-f. Aligning here improves consistency.Apply:
- <dt>`--component` <em>(alias `-c`)</em> <em>(required)</em></dt> + <dt>`--component` / `-c` <em>(required)</em></dt> <dd>Atmos component to unlock.</dd> - <dt>`--stack` <em>(alias `-s`)</em> <em>(required)</em></dt> + <dt>`--stack` / `-s` <em>(required)</em></dt> <dd>Atmos stack to unlock.</dd>website/docs/cli/commands/validate/validate-schema.mdx (1)
52-55: LGTM; optional enhancement: link to manifest docs.Consider linking “Atmos manifest file” to the relevant docs page for quicker navigation.
website/docs/cli/commands/helmfile/helmfile-generate-varfile.mdx (1)
49-58: LGTM; optional clarification for --file default name.If there’s a predictable default filename pattern, consider adding a brief example (e.g., derived from context) to reduce ambiguity.
website/docs/cli/commands/completion.mdx (1)
123-126: LGTM; optional note about case sensitivity.If the CLI requires lowercase values (e.g.,
powershell), consider noting that explicitly.website/docs/cli/commands/describe/describe-component.mdx (1)
71-95: LGTM; minor copy tweak for --pager and defaults.
- Use “Enable/disable” phrasing (consistent order).
- Consider stating the default and accepted values for
--pager.website/docs/cli/commands/workflow.mdx (2)
90-93: Annotate argument optionality for consistencyInteractive mode supports no args, so mark workflow_name as optional.
- <dt>`workflow_name`</dt> - <dd>Workflow name</dd> + <dt>`workflow_name` <em>(optional)</em></dt> + <dd>Workflow name.</dd>
97-109: Clarify conditional requirement for --file--file is required when specifying a workflow_name, but not for interactive UI. Clarify in description.
- <dt>`--file` / `-f` <em>(required)</em></dt> - <dd>File name where the workflow is defined.</dd> + <dt>`--file` / `-f` <em>(required)</em></dt> + <dd>Workflow manifest file. Required when specifying `workflow_name`; not required for interactive UI.</dd>website/docs/cli/commands/terraform/terraform-plan-diff.mdx (1)
34-46: Minor consistency nit: prefer long flag before short aliasElsewhere in this PR, flags are shown as
--long/-s. Mirror that here.- <dt>`-s` / `--stack` <em>(required)</em></dt> + <dt>`--stack` / `-s` <em>(required)</em></dt>website/docs/cli/commands/validate/validate-stacks.mdx (1)
93-95: Optional: Mention the default (embedded) schema inline.Adding the default behavior here improves scannability without scrolling to the section below.
Apply this diff:
- <dd>Path to JSON Schema to validate Atmos stack manifests.<br/>Can be a URL, an absolute path,<br/>or a path relative to the `base_path` setting in `atmos.yaml`.</dd> + <dd>Path to JSON Schema to validate Atmos stack manifests (defaults to the embedded schema if not provided).<br/>Can be a URL, an absolute path,<br/>or a path relative to the `base_path` setting in `atmos.yaml`.</dd>
📜 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.
📒 Files selected for processing (21)
website/docs/cli/commands/atlantis/atlantis-generate-repo-config.mdx(1 hunks)website/docs/cli/commands/aws/aws-eks-update-kubeconfig.mdx(1 hunks)website/docs/cli/commands/completion.mdx(1 hunks)website/docs/cli/commands/describe/describe-component.mdx(1 hunks)website/docs/cli/commands/describe/describe-config.mdx(1 hunks)website/docs/cli/commands/describe/describe-stacks.mdx(1 hunks)website/docs/cli/commands/describe/describe-workflows.mdx(1 hunks)website/docs/cli/commands/helmfile/helmfile-generate-varfile.mdx(1 hunks)website/docs/cli/commands/helmfile/usage.mdx(1 hunks)website/docs/cli/commands/list/list-components.mdx(1 hunks)website/docs/cli/commands/list/list-stacks.mdx(1 hunks)website/docs/cli/commands/pro/pro-lock.mdx(1 hunks)website/docs/cli/commands/pro/pro-unlock.mdx(1 hunks)website/docs/cli/commands/terraform/terraform-plan-diff.mdx(1 hunks)website/docs/cli/commands/validate/validate-component.mdx(1 hunks)website/docs/cli/commands/validate/validate-editorconfig.mdx(1 hunks)website/docs/cli/commands/validate/validate-schema.mdx(1 hunks)website/docs/cli/commands/validate/validate-stacks.mdx(1 hunks)website/docs/cli/commands/vendor/vendor-pull.mdx(1 hunks)website/docs/cli/commands/version.mdx(1 hunks)website/docs/cli/commands/workflow.mdx(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in website/ when adding features
Ensure consistency between CLI help text and website documentation
Follow the website's documentation structure and style
Keep website code in website/ and follow its architecture/style; test changes locally
Keep CLI and website documentation in sync; document new features with examples and use cases
Files:
website/docs/cli/commands/completion.mdxwebsite/docs/cli/commands/workflow.mdxwebsite/docs/cli/commands/validate/validate-component.mdxwebsite/docs/cli/commands/validate/validate-schema.mdxwebsite/docs/cli/commands/atlantis/atlantis-generate-repo-config.mdxwebsite/docs/cli/commands/describe/describe-stacks.mdxwebsite/docs/cli/commands/validate/validate-editorconfig.mdxwebsite/docs/cli/commands/describe/describe-component.mdxwebsite/docs/cli/commands/list/list-stacks.mdxwebsite/docs/cli/commands/vendor/vendor-pull.mdxwebsite/docs/cli/commands/describe/describe-config.mdxwebsite/docs/cli/commands/list/list-components.mdxwebsite/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/aws/aws-eks-update-kubeconfig.mdxwebsite/docs/cli/commands/terraform/terraform-plan-diff.mdxwebsite/docs/cli/commands/validate/validate-stacks.mdxwebsite/docs/cli/commands/pro/pro-lock.mdxwebsite/docs/cli/commands/describe/describe-workflows.mdxwebsite/docs/cli/commands/version.mdxwebsite/docs/cli/commands/helmfile/helmfile-generate-varfile.mdxwebsite/docs/cli/commands/pro/pro-unlock.mdx
website/docs/cli/commands/**/*.mdx
📄 CodeRabbit inference engine (CLAUDE.md)
website/docs/cli/commands/**/*.mdx: All new commands/flags/parameters MUST have Docusaurus documentation using definition listsinstead of tables for arguments and flags
Follow Docusaurus conventions from existing files including consistent section ordering (Usage → Examples → Arguments → Flags), use purpose notes and screengrabs
Files:
website/docs/cli/commands/completion.mdxwebsite/docs/cli/commands/workflow.mdxwebsite/docs/cli/commands/validate/validate-component.mdxwebsite/docs/cli/commands/validate/validate-schema.mdxwebsite/docs/cli/commands/atlantis/atlantis-generate-repo-config.mdxwebsite/docs/cli/commands/describe/describe-stacks.mdxwebsite/docs/cli/commands/validate/validate-editorconfig.mdxwebsite/docs/cli/commands/describe/describe-component.mdxwebsite/docs/cli/commands/list/list-stacks.mdxwebsite/docs/cli/commands/vendor/vendor-pull.mdxwebsite/docs/cli/commands/describe/describe-config.mdxwebsite/docs/cli/commands/list/list-components.mdxwebsite/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/aws/aws-eks-update-kubeconfig.mdxwebsite/docs/cli/commands/terraform/terraform-plan-diff.mdxwebsite/docs/cli/commands/validate/validate-stacks.mdxwebsite/docs/cli/commands/pro/pro-lock.mdxwebsite/docs/cli/commands/describe/describe-workflows.mdxwebsite/docs/cli/commands/version.mdxwebsite/docs/cli/commands/helmfile/helmfile-generate-varfile.mdxwebsite/docs/cli/commands/pro/pro-unlock.mdx
🧠 Learnings (17)
📓 Common learnings
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : All new commands/flags/parameters MUST have Docusaurus documentation using definition lists <dl> instead of tables for arguments and flags
Learnt from: samtholiya
PR: cloudposse/atmos#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: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : Follow Docusaurus conventions from existing files including consistent section ordering (Usage → Examples → Arguments → Flags), use purpose notes and screengrabs
Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-09-23T02:30:42.362Z
Learning: Applies to website/** : Ensure consistency between CLI help text and website documentation
Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-09-23T02:30:42.362Z
Learning: Applies to website/** : Keep CLI and website documentation in sync; document new features with examples and use cases
Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-09-23T02:30:42.362Z
Learning: Applies to README.md : Update README.md when adding new commands and features
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to cmd/markdown/*_usage.md : Examples for CLI commands must be embedded as markdown in cmd/markdown/*_usage.md files
📚 Learning: 2025-09-23T03:44:59.111Z
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : All new commands/flags/parameters MUST have Docusaurus documentation using definition lists <dl> instead of tables for arguments and flags
Applied to files:
website/docs/cli/commands/completion.mdxwebsite/docs/cli/commands/workflow.mdxwebsite/docs/cli/commands/validate/validate-component.mdxwebsite/docs/cli/commands/validate/validate-schema.mdxwebsite/docs/cli/commands/atlantis/atlantis-generate-repo-config.mdxwebsite/docs/cli/commands/describe/describe-stacks.mdxwebsite/docs/cli/commands/validate/validate-editorconfig.mdxwebsite/docs/cli/commands/describe/describe-component.mdxwebsite/docs/cli/commands/list/list-stacks.mdxwebsite/docs/cli/commands/vendor/vendor-pull.mdxwebsite/docs/cli/commands/describe/describe-config.mdxwebsite/docs/cli/commands/list/list-components.mdxwebsite/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/aws/aws-eks-update-kubeconfig.mdxwebsite/docs/cli/commands/terraform/terraform-plan-diff.mdxwebsite/docs/cli/commands/validate/validate-stacks.mdxwebsite/docs/cli/commands/pro/pro-lock.mdxwebsite/docs/cli/commands/describe/describe-workflows.mdxwebsite/docs/cli/commands/version.mdxwebsite/docs/cli/commands/helmfile/helmfile-generate-varfile.mdxwebsite/docs/cli/commands/pro/pro-unlock.mdx
📚 Learning: 2025-09-23T03:44:59.111Z
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : Follow Docusaurus conventions from existing files including consistent section ordering (Usage → Examples → Arguments → Flags), use purpose notes and screengrabs
Applied to files:
website/docs/cli/commands/workflow.mdxwebsite/docs/cli/commands/validate/validate-component.mdxwebsite/docs/cli/commands/atlantis/atlantis-generate-repo-config.mdxwebsite/docs/cli/commands/validate/validate-editorconfig.mdxwebsite/docs/cli/commands/describe/describe-component.mdxwebsite/docs/cli/commands/describe/describe-config.mdxwebsite/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/helmfile/helmfile-generate-varfile.mdx
📚 Learning: 2025-01-09T22:27:25.538Z
Learnt from: samtholiya
PR: cloudposse/atmos#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:
website/docs/cli/commands/validate/validate-component.mdxwebsite/docs/cli/commands/describe/describe-component.mdxwebsite/docs/cli/commands/helmfile/usage.mdx
📚 Learning: 2025-09-23T03:44:59.111Z
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to pkg/datafetcher/schema/**.json : Update ALL schema files in pkg/datafetcher/schema/ when adding Atmos configuration options
Applied to files:
website/docs/cli/commands/validate/validate-schema.mdxwebsite/docs/cli/commands/validate/validate-stacks.mdx
📚 Learning: 2025-06-23T02:14:30.937Z
Learnt from: aknysh
PR: cloudposse/atmos#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:
website/docs/cli/commands/describe/describe-stacks.mdx
📚 Learning: 2025-01-19T15:49:15.593Z
Learnt from: samtholiya
PR: cloudposse/atmos#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:
website/docs/cli/commands/describe/describe-stacks.mdxwebsite/docs/cli/commands/describe/describe-component.mdxwebsite/docs/cli/commands/list/list-stacks.mdxwebsite/docs/cli/commands/helmfile/usage.mdx
📚 Learning: 2025-02-18T13:13:11.497Z
Learnt from: samtholiya
PR: cloudposse/atmos#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:
website/docs/cli/commands/list/list-stacks.mdxwebsite/docs/cli/commands/version.mdx
📚 Learning: 2024-11-12T13:06:56.194Z
Learnt from: osterman
PR: cloudposse/atmos#768
File: website/docs/cheatsheets/vendoring.mdx:70-70
Timestamp: 2024-11-12T13:06:56.194Z
Learning: In `atmos vendor pull --everything`, the `--everything` flag uses the TTY for TUI but is not interactive.
Applied to files:
website/docs/cli/commands/vendor/vendor-pull.mdxwebsite/docs/cli/commands/version.mdx
📚 Learning: 2025-09-05T14:57:37.360Z
Learnt from: RoseSecurity
PR: cloudposse/atmos#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:
website/docs/cli/commands/vendor/vendor-pull.mdxwebsite/docs/cli/commands/version.mdx
📚 Learning: 2024-10-21T17:51:53.976Z
Learnt from: osterman
PR: cloudposse/atmos#727
File: internal/exec/terraform.go:114-118
Timestamp: 2024-10-21T17:51:53.976Z
Learning: When `atmos terraform clean --everything` is used without specifying a component and without the `--force` flag, prompt the user for confirmation before deleting all components. Use the `--force` flag to skip the confirmation prompt.
Applied to files:
website/docs/cli/commands/vendor/vendor-pull.mdx
📚 Learning: 2025-02-03T06:00:11.419Z
Learnt from: samtholiya
PR: cloudposse/atmos#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:
website/docs/cli/commands/describe/describe-config.mdx
📚 Learning: 2025-02-11T08:21:33.143Z
Learnt from: shirkevich
PR: cloudposse/atmos#1034
File: website/docs/core-concepts/projects/configuration/stores.mdx:173-177
Timestamp: 2025-02-11T08:21:33.143Z
Learning: The parameter for configuring stack path delimiter in store configurations is consistently named `stack_delimiter` (not `stacks_delimiter`) across all store types in Atmos.
Applied to files:
website/docs/cli/commands/list/list-components.mdx
📚 Learning: 2025-09-23T03:44:59.111Z
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to cmd/markdown/*_usage.md : Examples for CLI commands must be embedded as markdown in cmd/markdown/*_usage.md files
Applied to files:
website/docs/cli/commands/helmfile/usage.mdx
📚 Learning: 2024-12-07T16:16:13.038Z
Learnt from: Listener430
PR: cloudposse/atmos#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:
website/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/helmfile/helmfile-generate-varfile.mdx
📚 Learning: 2025-09-13T16:39:20.007Z
Learnt from: samtholiya
PR: cloudposse/atmos#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:
website/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/version.mdx
📚 Learning: 2024-10-27T16:59:26.187Z
Learnt from: osterman
PR: cloudposse/atmos#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:
website/docs/cli/commands/version.mdx
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: website-deploy-preview
- GitHub Check: Analyze (go)
- GitHub Check: Lint (golangci)
- GitHub Check: Build (ubuntu-latest, linux)
- GitHub Check: Build (windows-latest, windows)
- GitHub Check: Build (macos-latest, macos)
- GitHub Check: Run pre-commit hooks
- GitHub Check: Summary
🔇 Additional comments (18)
website/docs/cli/commands/list/list-components.mdx (1)
61-64: LGTM.Consistent DL format and alias style (
--stack/-s). No issues.website/docs/cli/commands/describe/describe-config.mdx (1)
43-49: Verify default format matches CLI help.Doc states
jsonis default; double-check againstatmos describe config --helpto avoid drift.website/docs/cli/commands/helmfile/helmfile-generate-varfile.mdx (1)
42-45: LGTM.Argument converted correctly with required marker.
website/docs/cli/commands/describe/describe-component.mdx (1)
64-67: LGTM.Argument DL looks correct.
website/docs/cli/commands/aws/aws-eks-update-kubeconfig.mdx (2)
78-81: Arguments DL conversion LGTMArg formatting and optionality read correct given multiple invocation modes.
85-112: Flags DL conversion — verified against CLIMDX flags match registered CLI flags: --stack/-s, --profile, --role-arn, --name, --region, --kubeconfig, --alias, --dry-run, --verbose.
website/docs/cli/commands/validate/validate-component.mdx (2)
50-65: Flags DL conversion LGTMRequired stack and optional schema-related flags look accurate and clear.
43-46: Arguments DL conversion LGTMComponent is enforced at runtime in internal/exec/validate_component.go — ExecuteValidateComponentCmd returns an error if len(args) != 1, so the docs and CLI are consistent.
website/docs/cli/commands/validate/validate-editorconfig.mdx (1)
41-86: Solid DL migration; contents preservedFlags are faithfully converted and read well.
website/docs/cli/commands/version.mdx (1)
44-50: DL conversion LGTMFlags accurately reflected with clear descriptions.
website/docs/cli/commands/terraform/terraform-plan-diff.mdx (1)
27-30: Arguments DL conversion LGTMReads clean and matches usage.
website/docs/cli/commands/list/list-stacks.mdx (1)
62-65: DL conversion looks good — docs match CLI helpDocs list only
--component/-c(website/docs/cli/commands/list/list-stacks.mdx) and the CLI snapshot (cmd/markdown/atmos_list_stacks_usage.md) shows only-c <component>; no additional format/output flags found.website/docs/cli/commands/validate/validate-stacks.mdx (1)
92-95: Definition list conversion looks good.Meets the DL requirement and keeps semantics intact.
website/docs/cli/commands/describe/describe-stacks.mdx (1)
60-90: Conversion to definition list is consistent and clear.Optionality and aliases are called out well; reads cleanly.
website/docs/cli/commands/describe/describe-workflows.mdx (1)
44-53: LGTM on DL conversion and content.Flags, defaults, and aliases are preserved and consistent with examples below.
website/docs/cli/commands/helmfile/usage.mdx (2)
68-71: Arguments DL reads well.Required marker is clear and consistent.
75-84: Flags DL looks good.Aliases and required/optional annotations are consistent; copy is concise.
website/docs/cli/commands/pro/pro-lock.mdx (1)
51-55: Defaults verified — docs match implementation.
TTL defaults to 30 and message defaults to "Locked by Atmos" (implemented in internal/exec/pro.go; flag/help text in cmd/pro_lock.go).
…stacks The --sections flag documentation was missing 'component' from the enumerated list of available sections, even though examples in the documentation reference it. Added 'component' in alphabetical order between 'backend_type' and 'deps'.
The vendor-pull.mdx documentation was missing the --everything flag from the Flags section, even though it was referenced in usage examples. Added the flag with description 'Vendor all components' and marked as optional to match the formatting of other flags.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
website/docs/cli/commands/completion.mdx (1)
59-61: TabItem uses “label”, not “name”.Using “name” breaks the tab label rendering.
Apply this diff:
-<TabItem value="zsh" name="Zsh"> +<TabItem value="zsh" label="Zsh">
🧹 Nitpick comments (5)
website/docs/cli/commands/completion.mdx (2)
52-54: Fix code fence language for Bash reload snippet.It’s a Bash snippet; use bash for highlighting.
Apply this diff:
-```zsh +```bash source ~/.bashrc--- `26-26`: **Capitalize PowerShell when referring to the shell.** Keep brand casing consistent in prose. Apply this diff: ```diff -This command generates completion scripts for `Bash`, `Zsh`, `Fish` and `powershell`. +This command generates completion scripts for `Bash`, `Zsh`, `Fish` and `PowerShell`.website/docs/cli/commands/helmfile/usage.mdx (1)
76-85: Wrap flags and literals in<code>tags within definition lists
Replace backticks in<dt>/<dd>with<code>…</code>(e.g.,<code>--stack</code>,<code>stderr</code>,<code>/dev/null</code>).- <dt>`--stack` / `-s` <em>(required)</em></dt> + <dt><code>--stack</code> / <code>-s</code> <em>(required)</em></dt> <dd>Atmos stack.</dd> - <dt>`--dry-run` <em>(optional)</em></dt> + <dt><code>--dry-run</code> <em>(optional)</em></dt> <dd>Dry run.</dd> - <dt>`--redirect-stderr` <em>(optional)</em></dt> - <dd>File descriptor to redirect `stderr` to.<br/>Errors can be redirected to any file or any standard file descriptor<br/>(including `/dev/null`).</dd> + <dt><code>--redirect-stderr</code> <em>(optional)</em></dt> + <dd>File descriptor to redirect <code>stderr</code> to.<br/>Errors can be redirected to any file or any standard file descriptor<br/>(including <code>/dev/null</code>).</dd>website/docs/cli/commands/describe/describe-stacks.mdx (2)
61-91: Backticks inside HTML may not render as code in MDX. Prefertags.Within HTML blocks (
/
- /
- ), markdown backticks often aren’t parsed. Swap to
…to ensure consistent rendering.Example pattern to apply across this block:
- <dt>`--stack` / `-s` <em>(optional)</em></dt> + <dt><code>--stack</code> / <code>-s</code> <em>(optional)</em></dt>Please verify locally that backticks render as intended; if not, apply this change consistently to all inline code tokens in the Flags list.
77-79: Clarify support for “none” in --sections (used in examples).Examples use
--sections=none, but the description doesn’t mention it. Add a note so users know it’s accepted.Apply this diff:
- <dd>Output only the specified component sections.<br/>Available component sections: `backend`, `backend_type`, `component`, `deps`,<br/>`env`, `inheritance`, `metadata`, `remote_state_backend`,<br/>`remote_state_backend_type`, `settings`, `vars`.</dd> + <dd>Output only the specified component sections.<br/>Available component sections: `backend`, `backend_type`, `component`, `deps`,<br/>`env`, `inheritance`, `metadata`, `remote_state_backend`,<br/>`remote_state_backend_type`, `settings`, `vars`.<br/>Use `none` to output no sections.</dd>
📜 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 9b977d80b04a51f4e94bedbadb0df6ed4e2b043f and c2bfc7bbe426854b441afc7f7f8e75df69966faa.
📒 Files selected for processing (14)
website/docs/cli/commands/completion.mdx (1 hunks)website/docs/cli/commands/describe/describe-component.mdx (1 hunks)website/docs/cli/commands/describe/describe-config.mdx (1 hunks)website/docs/cli/commands/describe/describe-stacks.mdx (1 hunks)website/docs/cli/commands/describe/describe-workflows.mdx (1 hunks)website/docs/cli/commands/helmfile/helmfile-generate-varfile.mdx (1 hunks)website/docs/cli/commands/helmfile/usage.mdx (1 hunks)website/docs/cli/commands/list/list-stacks.mdx (1 hunks)website/docs/cli/commands/pro/pro-lock.mdx (1 hunks)website/docs/cli/commands/pro/pro-unlock.mdx (1 hunks)website/docs/cli/commands/validate/validate-stacks.mdx (1 hunks)website/docs/cli/commands/vendor/vendor-pull.mdx (1 hunks)website/docs/cli/commands/version.mdx (1 hunks)website/docs/cli/commands/workflow.mdx (1 hunks)
✅ Files skipped from review due to trivial changes (1)
- website/docs/cli/commands/workflow.mdx
🚧 Files skipped from review as they are similar to previous changes (10)
- website/docs/cli/commands/pro/pro-unlock.mdx
- website/docs/cli/commands/helmfile/helmfile-generate-varfile.mdx
- website/docs/cli/commands/describe/describe-component.mdx
- website/docs/cli/commands/pro/pro-lock.mdx
- website/docs/cli/commands/describe/describe-config.mdx
- website/docs/cli/commands/list/list-stacks.mdx
- website/docs/cli/commands/validate/validate-stacks.mdx
- website/docs/cli/commands/vendor/vendor-pull.mdx
- website/docs/cli/commands/describe/describe-workflows.mdx
- website/docs/cli/commands/version.mdx
🧰 Additional context used
📓 Path-based instructions (2)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in website/ when adding features
Ensure consistency between CLI help text and website documentation
Follow the website's documentation structure and style
Keep website code in website/ and follow its architecture/style; test changes locally
Keep CLI and website documentation in sync; document new features with examples and use cases
Files:
website/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/completion.mdxwebsite/docs/cli/commands/describe/describe-stacks.mdx
website/docs/cli/commands/**/*.mdx
📄 CodeRabbit inference engine (CLAUDE.md)
website/docs/cli/commands/**/*.mdx: All new commands/flags/parameters MUST have Docusaurus documentation using definition lists
instead of tables for arguments and flags
Follow Docusaurus conventions from existing files including consistent section ordering (Usage → Examples → Arguments → Flags), use purpose notes and screengrabs
Files:
website/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/completion.mdxwebsite/docs/cli/commands/describe/describe-stacks.mdx
🧠 Learnings (8)
📓 Common learnings
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : All new commands/flags/parameters MUST have Docusaurus documentation using definition lists <dl> instead of tables for arguments and flags
Learnt from: samtholiya
PR: cloudposse/atmos#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: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : Follow Docusaurus conventions from existing files including consistent section ordering (Usage → Examples → Arguments → Flags), use purpose notes and screengrabs
Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-09-23T02:30:42.362Z
Learning: Applies to README.md : Update README.md when adding new commands and features
Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-09-23T02:30:42.362Z
Learning: Applies to website/** : Ensure consistency between CLI help text and website documentation
Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-09-23T02:30:42.362Z
Learning: Applies to website/** : Keep CLI and website documentation in sync; document new features with examples and use cases
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to cmd/markdown/*_usage.md : Examples for CLI commands must be embedded as markdown in cmd/markdown/*_usage.md files
📚 Learning: 2025-09-23T03:44:59.111Z
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : All new commands/flags/parameters MUST have Docusaurus documentation using definition lists <dl> instead of tables for arguments and flags
Applied to files:
website/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/completion.mdxwebsite/docs/cli/commands/describe/describe-stacks.mdx
📚 Learning: 2025-09-23T03:44:59.111Z
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to website/docs/cli/commands/**/*.mdx : Follow Docusaurus conventions from existing files including consistent section ordering (Usage → Examples → Arguments → Flags), use purpose notes and screengrabs
Applied to files:
website/docs/cli/commands/helmfile/usage.mdx
📚 Learning: 2025-09-23T03:44:59.111Z
Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-23T03:44:59.111Z
Learning: Applies to cmd/markdown/*_usage.md : Examples for CLI commands must be embedded as markdown in cmd/markdown/*_usage.md files
Applied to files:
website/docs/cli/commands/helmfile/usage.mdx
📚 Learning: 2024-12-07T16:16:13.038Z
Learnt from: Listener430
PR: cloudposse/atmos#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:
website/docs/cli/commands/helmfile/usage.mdx
📚 Learning: 2025-01-19T15:49:15.593Z
Learnt from: samtholiya
PR: cloudposse/atmos#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:
website/docs/cli/commands/helmfile/usage.mdxwebsite/docs/cli/commands/describe/describe-stacks.mdx
📚 Learning: 2025-09-13T16:39:20.007Z
Learnt from: samtholiya
PR: cloudposse/atmos#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:
website/docs/cli/commands/helmfile/usage.mdx
📚 Learning: 2025-01-09T22:27:25.538Z
Learnt from: samtholiya
PR: cloudposse/atmos#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:
website/docs/cli/commands/helmfile/usage.mdx
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)
- GitHub Check: Build (windows-latest, windows)
- GitHub Check: Build (ubuntu-latest, linux)
- GitHub Check: Build (macos-latest, macos)
- GitHub Check: Lint (golangci)
- GitHub Check: Analyze (go)
- GitHub Check: website-deploy-preview
- GitHub Check: Summary
Andriy Knysh (aknysh)
approved these changes
Sep 24, 2025
|
These changes were released in v1.191.1-test.0. |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
what
<dl>,<dt>,<dd>tagswhy
Changes Made
Files Updated (21 total)
atlantis/atlantis-generate-repo-config.mdxaws/aws-eks-update-kubeconfig.mdxcompletion.mdxdescribe/describe-component.mdxdescribe/describe-config.mdxdescribe/describe-stacks.mdxdescribe/describe-workflows.mdxhelmfile/helmfile-generate-varfile.mdxhelmfile/usage.mdxlist/list-components.mdxlist/list-stacks.mdxpro/pro-lock.mdxpro/pro-unlock.mdxterraform/terraform-plan-diff.mdxvalidate/validate-component.mdxvalidate/validate-editorconfig.mdxvalidate/validate-schema.mdxvalidate/validate-stacks.mdxvendor/vendor-pull.mdxversion.mdxworkflow.mdxConversion Details
Example Conversion
Before (table format):
After (definition list format):
references
Summary by CodeRabbit