CLI Command Naming FAQ
Short answers to the questions developers ask most about naming CLI commands.
Should CLI commands use kebab-case or snake_case?
Kebab-case (create-user). It matches Unix tradition, works everywhere shells do, and is the convention in the most widely used CLIs. Snake_case looks foreign next to ls, git, and docker.
Verb-noun or noun-verb — which order is better?
Verb-noun (create-user) reads most naturally and is the best default. Noun-verb (user-create) groups commands alphabetically by resource, which suits very large command sets. Pick one and apply it everywhere.
How many levels of subcommands should I use?
One level covers most tools; two levels (config set) suit larger CLIs with distinct domains. Three or more levels need strong justification — prefer flags over deeper nesting.
Should I provide short aliases for commands?
Sparingly. Arbitrary abbreviations block future command names and make help output harder to scan. Reserve aliases for the two or three most-typed commands, if any.
How should I name boolean flags?
Long form with double dashes and no value: --verbose, --dry-run, --force. Destructive actions should require confirmation by default, with --force opting out — never the reverse.
What about positional arguments vs flags?
Required, obvious inputs can be positional (mycli deploy production). Optional or non-obvious inputs should be flags (--output report.csv). When in doubt, use a flag — it's self-documenting.
How do I rename a command without breaking users?
Ship the new name, keep the old one as a deprecated alias that prints a warning, and remove it on a published schedule. Never rename silently in a patch release.
Do command names affect shell completion?
The names themselves don't, but consistent prefixes do: completion becomes genuinely useful when related commands share a namespace (config set, config get) instead of scattering.