cli-tool-architectlisted

# CLI Tool Architecture Language-agnostic conventions for command-line tools. Go-specific recipes use `spf13/cobra` + `spf13/pflag` + `spf13/viper`; Python-specific recipes use `typer`. Per-language stacks are canonical in [go-architect](../../languages/go-architect/SKILL.md) and [python-architect](../../languages/python-architect/SKILL.md). See [STACK.md](STACK.md) for additional CLI-specific libraries (output styling, alternative loggers). ## 1. Command structure - **Root + subcommands.** `tool <subcommand> [args] [flags]`. Mirrors `git`, `kubectl`, `docker`, `rsk`. Top-level flags are global; subcommand flags are scoped to that subcommand. - **One verb per subcommand.** `tool create user` is fine. `tool create-user-now` is not. - **Hierarchy when it reads naturally:** `tool resource action` (e.g. `kubectl get pods`, `aws s3 ls`). Skip if your tool has fewer than ~5 commands — flatten. - **`tool` alone (no subcommand) prints help.** Never run "the default action" — implicit behavior is the source of surprise commits and accidental deploys. - **Names: short, lowercase, single-word where possible.** `get`, `list`, `apply`, `delete`. Two words if they're a phrase: `get-config`. ## 2. Arguments vs flags - **Positional arguments** for the *required noun* of the verb: `tool delete <user-id>`. Use sparingly — every extra positional reduces clarity. - **Flags** for everything else. Required flags exist; mark them with `Required: true` (cobra) / `Option(...)` (typer) and docume