Agent RulesAgent Rules
CL

CLI Output & UX

Output formatting, color handling, progress indicators, and human vs machine-readable output patterns

Universal
Architecture
Use in BuilderAll Universal Options

Details

Language / Topic
_UUniversal
Category
Architecture

Rules

balanced
- Write data output to stdout and diagnostics (logs, progress, errors) to stderr. This enables piping: myapp list | grep active.
- Support --json flag for machine-readable output. Default to human-readable formatted output when stdout is a TTY.
- Detect TTY and suppress colors, progress bars, and interactive prompts when output is piped or redirected.
- Use color intentionally: red for errors, yellow for warnings, green for success, dim/gray for secondary info. Never use color as the only signal.
- Respect the NO_COLOR environment variable (https://no-color.org/) and --no-color flag. Never force color output.
- Show progress bars or spinners for operations taking more than 1 second. Include elapsed time and, when possible, an ETA.
- Format tabular output with aligned columns and headers. Use a compact format when there are many rows, detailed format for few rows.
- Use consistent output structure: for JSON mode, always return { "data": [...], "errors": [...] } so scripts can parse results uniformly.
- Add --verbose/-v (more detail), --quiet/-q (errors only), and --debug (internal diagnostics) flags. Stack verbosity: -vv for even more detail.
- Truncate long values in table output with ellipsis. Provide a --wide or --no-truncate flag to show full values.