CLI Tool Specification Template

Limit nesting to two levels maximum (e.g., `tool group command`). Three or more levels make the tool harder to discover and type. If you find yourself needing a third level, consider flattening the hierarchy or splitting into separate tools. Most successful CLIs like `git`, `docker`, and `kubectl` stay at two levels.

Use double-dash for full flag names (`--verbose`) and single-dash for single-character shortcuts (`-v`). This is the POSIX convention and what developers expect. Allow combining short flags (`-vq` for `--verbose --quiet`). Never use single-dash for multi-character flags.

Default to human-readable text for interactive use. Support `--format json` for scripts and automation. Some teams add `--format yaml` as well. The key rule is that JSON output should be stable. If you change the JSON schema, treat it as a breaking change and version your output format.

Store credentials in a dotfile in the user's home directory (e.g., `~/.toolrc/credentials`). Support environment variables as overrides for CI/CD environments (`TOOL_API_KEY`). Never require the user to pass credentials as command-line arguments since those appear in shell history. The [Technical PM Handbook](/technical-pm-guide) covers security considerations for developer-facing tools.

Include `--dry-run` on every command that modifies state (deployments, deletions, configuration changes). It is not needed for read-only commands like `list` or `status`. The dry-run output should show exactly what would happen, not just "no changes made." ---