---
name: create-cli-best-practices
description: Rules to create and maintain a GOOD CLI. Do not use for GUI-only design rules, web apps, or backend REST APIs.
compatibility: Antigravity / Gemini CLI
metadata:
  version: 0.1.14
---

Implement the CLI in `rust` or `go`.
Document any carlessian CLI in $GIC/ under installables.

# Language-Specific Recommendations

## Golang (Go)

Recommended tools and libraries:
* **Flags & Config:** Use [Cobra](https://github.com/spf13/cobra) (potentially combined with [Viper](https://github.com/spf13/viper) for configuration management) if you want to have subcommands, multiple flags, config file support, etc.
* **Terminal UIs (TUIs):** [Bubble Tea](https://github.com/charmbracelet/bubbletea) from Charm is **highly suggested** if Go is the language you choose! It makes building beautiful, interactive terminal user interfaces extremely clean, structured, and easy (following the Elm architecture).

# Convention on CLI

* **Keep Files Small:** Prefer smaller files/modules to a single big monolithic file. It'll be harder to manage in rebases.
* **Honor NO_COLOR:** Always honor the `NO_COLOR` environment variable (as per [no-color.org](https://no-color.org)).
* **Watch Mode Compatibility:** Make sure the CLI works well in `watch` scenarios (e.g., handling rapid polling, disabling terminal clearing or color escape sequences if they break watch mode).
* **Deterministic Ordering:** Always sort outputs (sets/lists/fields) deterministically to prevent glitches in `watch <cli>` and noisy diffs in structured output (JSON/YAML).
* **Execution Speed & Performance:** Build blazing fast Rust/Go CLIs (target <100ms startup) and keep list/default commands instantaneous (redirecting slow 10s+ default commands to help) by caching slow tasks locally (1h/1d duration) or placing long-running operations explicitly in the command name.

Ensure all commands support the following flags:

* `--help` / `-h`: Shows comprehensive usage and help.
* `--version` / `-v`: Shows the version. Ideally, check if the version is the latest at startup (if this can be done extremely fast, e.g., local version file or quick curl from public GitHub).
* `--dry-run` / `-n`: Allows users and agents to preview mutations without executing them. Output structured JSON detailing what would change.

# Riccardo-Specific Rules

1. **Colors:** Use colors! For frequently run or critical actions, use **WHITE** or **YELLOW**. For interesting/optional outputs, use **CYAN**.
2. **Terminal Standards:** Align with Linux directory coloring standards (e.g., green for executables, blue for directories).
3. **Emojis:** Use emojis to convey status and metadata (e.g., folder emojis, color status indicators for priorities).
4. **Emoji Safety:** Choose cross-platform emojis. Avoid flag emojis (which don't render well on some OSs) and be mindful that wide/multibyte emojis can disrupt tab/column alignment.
5. **Layout:** Ensure table and listing alignment is immaculate.

# AI-Friendly CLI Patterns

Since AI agents are prime consumers of command-line tools, design the CLI to be AI-friendly:

* **Format Options (`--format`):** Support structured output (`json`, `yaml`, `csv`). AIs parse JSON easily, while humans prefer YAML. Allow colors to be disabled via `--no-color` or `NO_COLOR=1`.
* **Pagination:** Support pagination parameters to help agents and humans navigate large data sets without blowing their context window or screen buffer. Use standard flags like `--max-items 100` and `--page 2` to retrieve the second batch (items 101-200).
* **Idempotency & exit codes:** Make commands idempotent (e.g., like `kubectl apply`). If a conflict exists, return unique exit codes (like `5` for "already exists") to facilitate programmatic recovery.
* **Composability (`--quiet` / `-q`):** Output bare values (one per line, no decorative borders, no tables) for easy piping into other commands or shell scripts.
* **Non-Interactive Bypasses (`--yes`, `--force`, or `--non-interactive`):** Allow bypassing human prompt queries. Always fail-fast or auto-bypass prompts when `stdin` is not a TTY (non-interactive terminals) to avoid hanging the agent. When a command requires interaction, explicitly document how to bypass it (e.g., "Warning: this part is interactive. To avoid interaction, ensure that `ENV[PINCO]` and `ENV[PALLO]` are set, or use `--force`").
* **Actionable Errors:** Ensure errors return machine-parseable strings (like `image_not_found` in the JSON/stderr payload), output the failing input, and provide suggestions/remediation commands.
* **AI-Specific Help (`--ai-help`):** Every CLI tool MUST have both a `--help` (for humans) and `--ai-help` (for AI). The `--ai-help` flag should output Markdown and provide:
  1. **Uses of the CLI for AI vs Human:** Explain how an AI should use the CLI differently from a human (e.g., advising the AI to call with `--json`, `--format=json | jq`, or `--quiet`).
  2. **Added Context:** Provide all relevant context in Markdown, such as where the script is located, where it is built, where additional context or documentation can be found, and references to any related skills.
  The standard `--help` output MUST mention the availability of `--ai-help` so agents can easily discover it.

# LLM Support

Do not run LLM calls implicitly or block executions indefinitely on rogue AI completions. Adhere to the Principle of Least Astonishment (POLA). Signify any LLM usage explicitly:

* `--llm-classify` or similar flags.
* `--long-running-summarization` to signal high execution latency to the user.

# Readings

* [Writing CLI Tools That AI Agents Actually Want to Use](https://dev.to/uenyioha/writing-cli-tools-that-ai-agents-actually-want-to-use-39no) (Ugo Enyioha)
* [Stop Wasting 89% of Your AI Agent's Tokens on CLI Noise](https://alies.dev/articles/cli-output-for-ai/) (Alies Lapatsin) — Useful, but not too much unless you write PHP.
* [no-color.org](https://no-color.org) — The `NO_COLOR` standard