CLI Command Naming Guide

The conventions behind CLIs that feel obvious: verb-first commands, kebab-case, discoverable grouping, and consistent flags.

Start with the verb

Commands are actions, so lead with one: create-user, delete-profile, list-services. Verb-noun ordering reads naturally in English and matches the most widely used tools. The noun-verb alternative (user-create) groups related commands alphabetically, which some teams prefer for large CLIs — the pattern reference compares both.

mycli create-user
mycli delete-profile
mycli list-services

Lowercase, hyphenated, no surprises

Command names should be lowercase single words where possible, kebab-case when multiple words are unavoidable: generate-report, install-plugin, update-config. Avoid camelCase (generateReport) and snake_case (update_config) — they fight shell conventions and look foreign next to standard Unix commands. Generate candidates with the free command name generator to stay in kebab-case by default.

Topics are nouns, commands are verbs

A widely used structure, visible in tools like Docker and gcloud, treats the topic as a (usually plural) noun and the operation as a verb:

docker container create
gcloud compute instances list
mycli users invite

This noun-verb-at-depth ordering scales: the topic groups everything about one resource, and the verbs stay consistent across topics (create, list, delete mean the same thing everywhere).

Design for discoverability

Users learn a CLI through --help, not documentation. That means related commands should be guessable: if config-set exists, config-get and config-reset should too, with the same flag names and output shapes. Group commands with common prefixes so --help output reads as a menu, not a miscellany.

Avoid ambiguity

Don't ship both update and upgrade — nobody can keep them straight, including you in six months. Don't allow arbitrary abbreviations; they block future command names. And don't add a catch-all run or do command: it becomes a junk drawer that prevents the command set from ever becoming coherent.

Keep subcommand depth shallow

One level (create-user) covers most tools. Two levels (config set) suit larger CLIs with distinct domains. Three or more levels need a strong justification — each level multiplies the names users must memorize. Prefer flags over deeper nesting for variations: deploy --dry-run beats deploy dry run.

Flags follow the same rules

Long flags use double dashes and kebab-case (--output-file, --dry-run); short flags use a single dash and one character (-o, -v). Boolean flags take no value (--verbose, not --verbose=true). Reuse standard flag names instead of inventing new ones: --help, --version, --json, --force, --quiet.