cli-tools · git:20261113.9a6c905 · 2026-11-13 · sha256 00051b65a347dd6e
cli-tools git:20261113.9a6c905A
Immutable. This exact content never changes and is served at /api/v1/blob/00051b65a347dd6e.
---
description: cli-tools rules
alwaysApply: true
---
# CLI Tools Conventions
> **Priority**: HIGH - Apply to CLI/terminal tools
> **Source**: codebase-reviewer, scripts AGENTS.md
## CLI integration tests
CLI tools need integration tests that verify:
- Command execution with various inputs
- Exit codes (0 for success, non-zero for errors)
- Output format correctness
- Error message quality
## Shell Script Standards
### Self-Contained
Scripts should be:
- Executable without external setup
- Include all needed helpers inline
- Document dependencies at top
### Robust
Scripts should:
- Use `set -euo pipefail`
- Handle empty inputs gracefully
- Quote all variables
- Provide helpful error messages
### macOS-Aware
Test on macOS and Linux:
- BSD vs GNU tool differences
- Path conventions
- Available commands
## Output Patterns
### Progress Indicators
```bash
echo "Processing files..."
for file in "${files[@]}"; do
echo " - $file"
process "$file"
done
echo "Done. Processed ${#files[@]} files."
```
### Error Output
```bash
# Errors to stderr
echo "Error: File not found: $file" >&2
exit 1
```
### Exit Codes
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Misuse/invalid args |
| 126 | Permission denied |
| 127 | Command not found |
## Help Text Pattern
```bash
usage() {
cat << EOF
Usage: ${0##*/} [OPTIONS] <input>
Description of what the command does.
Options:
-h, --help Show this help message
-v, --verbose Enable verbose output
-o, --output Output directory (default: .)
Examples:
${0##*/} input.txt
${0##*/} -v -o ./out input.txt
EOF
}
```
<!-- golden-agents:generated -->