cloudposse
diff --git a/‎CLAUDE.md‎
Lines changed: 169 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 169 additions & 0 deletions
diff --git a/‎cmd/about/about.go‎
Lines changed: 2 additions & 3 deletions b/‎cmd/about/about.go‎
Lines changed: 2 additions & 3 deletions
diff --git a/‎cmd/about/about_test.go‎
Lines changed: 8 additions & 24 deletions b/‎cmd/about/about_test.go‎
Lines changed: 8 additions & 24 deletions
diff --git a/‎cmd/internal/registry.go‎
Lines changed: 6 additions & 0 deletions b/‎cmd/internal/registry.go‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎cmd/root.go‎
Lines changed: 30 additions & 1 deletion b/‎cmd/root.go‎
Lines changed: 30 additions & 1 deletion
diff --git a/‎docs/developing-atmos-commands.md‎
Lines changed: 1 addition & 0 deletions b/‎docs/developing-atmos-commands.md‎
Lines changed: 1 addition & 0 deletions
@@ -125,6 +125,170 @@ func ProcessAll(ctx context.Context, items []Item) error {
 
 **Context should be first parameter** in functions that accept it.
 
+### I/O and UI Usage (MANDATORY)
+Atmos separates I/O (streams) from UI (formatting) for clarity and testability.
+
+**Two-layer architecture:**
+- **I/O Layer** (`pkg/io/`) - Stream access (stdout/stderr/stdin), terminal capabilities, masking
+- **UI Layer** (`pkg/ui/`) - Formatting (colors, styles, markdown rendering)
+
+**Terminal as Text UI:**
+The terminal window is effectively a text-based user interface (TextUI) for our CLI. Anything intended for user interaction—menus, prompts, animations, progress indicators—should be rendered to the terminal as UI output (stderr). Data intended for processing, piping, or machine consumption goes to the data channel (stdout).
+
+**Access pattern:**
+```go
+import (
+    iolib "github.com/cloudposse/atmos/pkg/io"
+    "github.com/cloudposse/atmos/pkg/ui"
+)
+
+// I/O context initialized in cmd/root.go PersistentPreRun
+// Available globally after flag parsing via data.Writer() and ui package functions
+```
+
+**Output functions (use these):**
+```go
+// Data channel (stdout) - for pipeable output
+data.Write("result")                // Plain text to stdout
+data.Writef("value: %s", val)       // Formatted text to stdout
+data.Writeln("result")              // Plain text with newline to stdout
+data.WriteJSON(structData)          // JSON to stdout
+data.WriteYAML(structData)          // YAML to stdout
+
+// UI channel (stderr) - for human messages
+ui.Write("Loading configuration...")            // Plain text (no icon, no color, stderr)
+ui.Writef("Processing %d items...", count)      // Formatted text (no icon, no color, stderr)
+ui.Writeln("Done")                              // Plain text with newline (no icon, no color, stderr)
+ui.Success("Deployment complete!")              // ✓ Deployment complete! (green, stderr)
+ui.Error("Configuration failed")                // ✗ Configuration failed (red, stderr)
+ui.Warning("Deprecated feature")                // ⚠ Deprecated feature (yellow, stderr)
+ui.Info("Processing components...")             // ℹ Processing components... (cyan, stderr)
+
+// Markdown rendering
+ui.Markdown("# Help\n\nUsage...")               // Rendered to stdout (data)
+ui.MarkdownMessage("**Error:** Invalid config") // Rendered to stderr (UI)
+```
+
+**Decision tree:**
+```
+What am I outputting?
+
+├─ Pipeable data (JSON, YAML, results)
+│  └─ Use data.Write(), data.Writef(), data.Writeln()
+│     data.WriteJSON(), data.WriteYAML()
+│
+├─ Plain UI messages (no icon, no color)
+│  └─ Use ui.Write(), ui.Writef(), ui.Writeln()
+│
+├─ Status messages (with icons and colors)
+│  └─ Use ui.Success(), ui.Error(), ui.Warning(), ui.Info()
+│
+└─ Formatted documentation
+   ├─ Help text, usage → ui.Markdown() (stdout)
+   └─ Error details → ui.MarkdownMessage() (stderr)
+```
+
+**Anti-patterns (DO NOT use):**
+```go
+// WRONG: Direct stream access
+fmt.Fprintf(os.Stdout, ...)  // Use data.Printf() instead
+fmt.Fprintf(os.Stderr, ...)  // Use ui.Success/Error/etc instead
+fmt.Println(...)             // Use data.Println() instead
+
+// WRONG: Will be blocked by linter
+io := iolib.NewContext()
+fmt.Fprintf(io.Data(), ...)  // Use data.Printf() instead
+```
+
+**Why this matters:**
+
+**Zero-Configuration Degradation:**
+Write code assuming a full-featured TTY - the system automatically handles everything:
+- ✅ **Color degradation** - TrueColor → 256 → 16 → None (respects NO_COLOR, CLICOLOR, terminal capability)
+- ✅ **Width adaptation** - Automatically wraps to terminal width or config max_width
+- ✅ **TTY detection** - Piped/redirected output becomes plain text automatically
+- ✅ **CI detection** - Detects CI environments and disables interactivity
+- ✅ **Markdown rendering** - Degrades gracefully from styled to plain text
+- ✅ **Icon support** - Shows icons in capable terminals, omits in others
+
+**Security & Reliability:**
+- ✅ **Automatic secret masking** - AWS keys, tokens, passwords masked before output
+- ✅ **Format-aware masking** - Handles JSON/YAML quoted variants
+- ✅ **No leakage** - Secrets never reach stdout/stderr/logs
+- ✅ **Pattern-based** - Detects common secret patterns automatically
+
+**Developer Experience:**
+- ✅ **No capability checking** - Never write `if tty { color() } else { plain() }`
+- ✅ **No manual masking** - Never write `redact(secret)` before output
+- ✅ **No stream selection** - Just use `data.*` (stdout) or `ui.*` (stderr)
+- ✅ **Testable** - Mock data.Writer() and ui functions for unit tests
+- ✅ **Enforced by linter** - Prevents direct fmt.Fprintf usage
+
+**User Experience:**
+- ✅ **Respects preferences** - Honors --no-color, --redirect-stderr, NO_COLOR env
+- ✅ **Pipeline friendly** - `atmos deploy | tee log.txt` works perfectly
+- ✅ **Accessibility** - Works in all terminal environments (screen readers, etc.)
+- ✅ **Consistent** - Same code path for all output, fewer bugs
+
+**Force Flags (for screenshot generation):**
+Use these flags to generate consistent output regardless of environment:
+- `--force-tty` / `ATMOS_FORCE_TTY=true` - Force TTY mode with sane defaults (width=120, height=40) when terminal detection fails
+- `--force-color` / `ATMOS_FORCE_COLOR=true` - Force TrueColor output even when not a TTY
+
+**Flag behavior:**
+- `--color` - Enables color **only if TTY** (respects terminal capabilities)
+- `--force-color` - Forces TrueColor **even for non-TTY** (for screenshots)
+- `--no-color` - Disables all color
+- `terminal.color` in atmos.yaml - Same as `--color` (respects TTY)
+
+**Example:**
+```bash
+# Generate screenshot with consistent output (using flags)
+atmos terraform plan --force-tty --force-color | screenshot.sh
+
+# Generate screenshot with consistent output (using env vars)
+ATMOS_FORCE_TTY=true ATMOS_FORCE_COLOR=true atmos terraform plan | screenshot.sh
+
+# Normal usage - automatically detects terminal
+atmos terraform plan
+
+# Piped output - automatically disables color
+atmos terraform output | jq .vpc_id
+```
+
+See `pkg/io/example_test.go` for comprehensive examples.
+
+### Secret Masking with Gitleaks
+
+Atmos uses Gitleaks pattern library (120+ patterns) for comprehensive secret detection:
+
+```yaml
+# atmos.yaml
+settings:
+  terminal:
+    mask:
+      patterns:
+        library: "gitleaks"  # Use Gitleaks patterns (default)
+        categories:
+          aws: true          # Enable AWS secret detection
+          github: true       # Enable GitHub token detection
+```
+
+Disable specific categories to reduce false positives:
+```yaml
+settings:
+  terminal:
+    mask:
+      patterns:
+        categories:
+          generic: false  # Disable generic patterns
+```
+
+Disable masking for debugging:
+```bash
+atmos terraform plan --mask=false
+```
+
 ### Package Organization (MANDATORY)
 - **Avoid utils package bloat** - Don't add new functions to `pkg/utils/`
 - **Create purpose-built packages** - New functionality gets its own package in `pkg/`
@@ -353,6 +517,11 @@ Follow template (what/why/references).
 - Tag `feature`/`enhancement`/`bugfix` (user-facing) or `contributors` (internal changes)
 - CI will fail without blog post
 
+**Blog post authorship:**
+- Author should always be the committer (the one who opened the PR)
+- Use GitHub username in authors list, not generic "atmos" or "cloudposse"
+- Add author to `website/blog/authors.yml` if not already present
+
 Use `no-release` label for docs-only changes.
 
 ### PR Tools
 
@@ -5,7 +5,7 @@ import (
 
 	"github.com/cloudposse/atmos/cmd/internal"
 	"github.com/cloudposse/atmos/cmd/markdown"
-	"github.com/cloudposse/atmos/pkg/utils"
+	"github.com/cloudposse/atmos/pkg/ui"
 )
 
 // aboutCmd represents the about command.
@@ -15,8 +15,7 @@ var aboutCmd = &cobra.Command{
 	Long:  `Display information about Atmos, its features, and benefits.`,
 	Args:  cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
-		utils.PrintfMarkdown("%s", markdown.AboutMarkdown)
-		return nil
+		return ui.Markdown(markdown.AboutMarkdown)
 	},
 }
 
 
@@ -1,39 +1,23 @@
 package about
 
 import (
-	"bytes"
-	"io"
-	"os"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 
-	"github.com/cloudposse/atmos/cmd/markdown"
+	iolib "github.com/cloudposse/atmos/pkg/io"
+	"github.com/cloudposse/atmos/pkg/ui"
 )
 
 func TestAboutCmd(t *testing.T) {
-	// Capture stdout since utils.PrintfMarkdown writes directly to os.Stdout.
-	oldStdout := os.Stdout
-	r, w, _ := os.Pipe()
-	os.Stdout = w
+	// Initialize I/O context and formatter for testing.
+	ioCtx, err := iolib.NewContext()
+	assert.NoError(t, err, "Failed to create I/O context")
+	ui.InitFormatter(ioCtx)
 
-	// Execute the command.
-	err := aboutCmd.RunE(aboutCmd, []string{})
+	// Execute the command - output goes to global I/O context.
+	err = aboutCmd.RunE(aboutCmd, []string{})
 	assert.NoError(t, err, "'atmos about' command should execute without error")
-
-	// Close the writer and restore stdout.
-	err = w.Close()
-	assert.NoError(t, err, "'atmos about' command should execute without error")
-
-	os.Stdout = oldStdout
-
-	// Read captured output.
-	var output bytes.Buffer
-	_, err = io.Copy(&output, r)
-	assert.NoError(t, err, "'atmos about' command should execute without error")
-
-	// Check if the output contains expected markdown content.
-	assert.Contains(t, output.String(), markdown.AboutMarkdown, "'atmos about' output should contain information about Atmos")
 }
 
 func TestAboutCommandProvider(t *testing.T) {
 
@@ -9,6 +9,12 @@ import (
 	errUtils "github.com/cloudposse/atmos/errors"
 )
 
+// Context keys for passing values through cobra command context.
+type contextKey string
+
+// IoContextKey is the key for storing io.Context in cobra command context.
+const IoContextKey contextKey = "ioContext"
+
 // registry is the global command registry instance.
 var registry = &CommandRegistry{
 	providers: make(map[string]CommandProvider),
 
@@ -26,13 +26,16 @@ import (
 	"github.com/cloudposse/atmos/internal/tui/templates/term"
 	tuiUtils "github.com/cloudposse/atmos/internal/tui/utils"
 	cfg "github.com/cloudposse/atmos/pkg/config"
+	"github.com/cloudposse/atmos/pkg/data"
 	"github.com/cloudposse/atmos/pkg/filesystem"
+	iolib "github.com/cloudposse/atmos/pkg/io"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/pager"
 	"github.com/cloudposse/atmos/pkg/perf"
 	"github.com/cloudposse/atmos/pkg/profiler"
 	"github.com/cloudposse/atmos/pkg/schema"
 	"github.com/cloudposse/atmos/pkg/telemetry"
+	"github.com/cloudposse/atmos/pkg/ui"
 	"github.com/cloudposse/atmos/pkg/ui/heatmap"
 	"github.com/cloudposse/atmos/pkg/utils"
 
@@ -189,6 +192,15 @@ var RootCmd = &cobra.Command{
 		if !isCompletionCommand(cmd) && err == nil {
 			telemetry.PrintTelemetryDisclosure()
 		}
+
+		// Initialize I/O context and global formatter after flag parsing.
+		// This ensures flags like --no-color, --redirect-stderr, --mask are respected.
+		ioCtx, ioErr := iolib.NewContext()
+		if ioErr != nil {
+			errUtils.CheckErrorPrintAndExit(fmt.Errorf("failed to initialize I/O context: %w", ioErr), "", "")
+		}
+		ui.InitFormatter(ioCtx)
+		data.InitWriter(ioCtx)
 	},
 	PersistentPostRun: func(cmd *cobra.Command, args []string) {
 		// Stop profiler after command execution.
@@ -257,7 +269,8 @@ func setupLogger(atmosConfig *schema.AtmosConfiguration) {
 	}
 
 	// If colors are disabled, clear the colors but keep the level strings.
-	if !atmosConfig.Settings.Terminal.IsColorEnabled() {
+	// Use stderr TTY detection since logs go to stderr.
+	if !atmosConfig.Settings.Terminal.IsColorEnabled(term.IsTTYSupportForStderr()) {
 		clearedStyles := &log.Styles{}
 		clearedStyles.Levels = make(map[log.Level]lipgloss.Style)
 		for k := range styles.Levels {
@@ -674,6 +687,9 @@ func init() {
 	RootCmd.PersistentFlags().StringSlice("config", []string{}, "Paths to configuration files (comma-separated or repeated flag)")
 	RootCmd.PersistentFlags().StringSlice("config-path", []string{}, "Paths to configuration directories (comma-separated or repeated flag)")
 	RootCmd.PersistentFlags().Bool("no-color", false, "Disable color output")
+	RootCmd.PersistentFlags().Bool("force-color", false, "Force color output even when not a TTY (useful for screenshots)")
+	RootCmd.PersistentFlags().Bool("force-tty", false, "Force TTY mode with sane defaults when terminal detection fails (useful for screenshots)")
+	RootCmd.PersistentFlags().Bool("mask", true, "Enable automatic masking of sensitive data in output (use --mask=false to disable)")
 	RootCmd.PersistentFlags().String("pager", "", "Enable pager for output (--pager or --pager=true to enable, --pager=false to disable, --pager=less to use specific pager)")
 	// Set NoOptDefVal so --pager without value means "true".
 	RootCmd.PersistentFlags().Lookup("pager").NoOptDefVal = "true"
@@ -687,6 +703,19 @@ func init() {
 	RootCmd.PersistentFlags().Bool("heatmap", false, "Show performance heatmap visualization after command execution (includes P95 latency)")
 	RootCmd.PersistentFlags().String("heatmap-mode", "bar", "Heatmap visualization mode: bar, sparkline, table (press 1-3 to switch in TUI)")
 
+	// Bind terminal flags to environment variables.
+	if err := viper.BindEnv("force-tty", "ATMOS_FORCE_TTY"); err != nil {
+		log.Error("Failed to bind ATMOS_FORCE_TTY environment variable", "error", err)
+	}
+	// Bind both ATMOS_FORCE_COLOR and CLICOLOR_FORCE to the same viper key (they are equivalent).
+	if err := viper.BindEnv("force-color", "ATMOS_FORCE_COLOR", "CLICOLOR_FORCE"); err != nil {
+		log.Error("Failed to bind ATMOS_FORCE_COLOR/CLICOLOR_FORCE environment variables", "error", err)
+	}
+	// Bind mask flag to environment variable.
+	if err := viper.BindEnv("mask", "ATMOS_MASK"); err != nil {
+		log.Error("Failed to bind ATMOS_MASK environment variable", "error", err)
+	}
+
 	// Bind environment variables for GitHub authentication.
 	// ATMOS_GITHUB_TOKEN takes precedence over GITHUB_TOKEN.
 	if err := viper.BindEnv("ATMOS_GITHUB_TOKEN", "ATMOS_GITHUB_TOKEN", "GITHUB_TOKEN"); err != nil {
 
@@ -659,6 +659,7 @@ See these commands for reference:
 
 ## Further Reading
 
+- [I/O and UI Output Guide](io-and-ui-output.md) - **How to handle output in commands**
 - [Command Registry Pattern PRD](prd/command-registry-pattern.md)
 - [Cobra Documentation](https://github.com/spf13/cobra)
 - [Atmos Custom Commands](/core-concepts/custom-commands)