Skip to main content

Comprehensive Terraform Documentation and Enhanced Help System

· 3 min read
Erik Osterman
Erik Osterman
Founder @ Cloud Posse

We're excited to announce major improvements to Atmos documentation, making it easier than ever to understand and use Terraform commands with Atmos. This release focuses on comprehensive command documentation, automated screengrab generation, and an improved help system.

Complete Terraform Command Documentation​

We've added comprehensive documentation for all Terraform commands integrated with Atmos. Each command now includes:

  • Detailed usage examples with real-world scenarios
  • Complete flag reference with descriptions and defaults
  • Atmos-specific behavior explanations
  • Visual screengrabs showing actual CLI output
  • Backend configuration details and limitations

Key additions include:

  • Terraform planfile workflow documentation with security considerations
  • All Terraform subcommands (plan, apply, destroy, validate, fmt, output, etc.)
  • Best practices for using Terraform with Atmos.

View Terraform Documentation

Improved Help System​

The help system has been completely refactored for better maintainability and user experience:

  • Reduced cognitive complexity - Large functions split into smaller, testable units
  • Consistent formatting - All help text now uses proper markdown rendering
  • Better color profiles - Automatic detection with TrueColor, ANSI256, and ASCII fallbacks
  • Performance tracking - Built-in instrumentation for monitoring command execution

Example improvements:

  • renderFlags() function reduced from 94 lines to focused 20-line implementation
  • configureWriter() split into 5 specialized functions
  • Added comprehensive unit tests for help rendering logic

Screengrab Generation Infrastructure​

We've built a complete system for generating accurate, up-to-date CLI help screengrabs:

  • Automated generation - All help screengrabs generated from actual CLI output
  • Color preservation - ANSI colors converted to HTML for documentation
  • Docker/Podman support - Cross-platform screengrab generation
  • CI/CD integration - GitHub Actions workflow for automatic updates

This ensures our documentation always reflects the actual CLI behavior.

Documentation Fixes​

Numerous documentation improvements including:

  • Fixed broken links across the documentation site
  • Corrected Terraform command examples
  • Updated helmfile sync description to accurately reflect behavior
  • Added security warnings for credential handling in planfiles
  • Improved Markdown formatting consistency

Upgrade Notes​

This release maintains backward compatibility. To take advantage of the new features:

  1. Update to the latest Atmos version
  2. Review the new Terraform documentation
  3. Check your workflows against the updated command descriptions

Contributors​

This release includes contributions from the Atmos team and community. Thank you to everyone who provided feedback, reported issues, and contributed code!

For the complete list of changes, see the GitHub release notes.

Have questions or feedback? Join us on Slack or open an issue on GitHub.