CLI command aliases: a practical guide
Shortcuts users love or shortcuts that haunt you? How to design command aliases that speed up experts without confusing everyone else.
What an alias is (and is not)
An alias is an alternate name for a command: mycli create-user also answers to mycli cu. Aliases do not add functionality — they add speed for frequent users and forgiveness for misremembered names. The canonical command name remains the documented, stable interface; the alias is a convenience layer on top. That distinction matters: aliases can be added and removed far more freely than canonical names, which is exactly what makes them safe to experiment with.
When aliases earn their keep
- Long canonical names.
generate-quarterly-compliance-reportbegs forgen-reportorgqr. - High-frequency commands. If telemetry (or your own usage) shows a command runs dozens of times a day, an alias pays for itself immediately.
- Common misspellings and synonyms. Users will type
removewhen you named itdelete. An alias absorbs the mistake instead of punishing it. - Migration bridges. Renamed a command? Keep the old name as a deprecated alias with a warning, and existing scripts keep working.
When they do not: for rarely used commands (the alias is another thing to document and maintain), or as a substitute for fixing a bad canonical name — if everyone needs the alias, the canonical name is wrong. See the CLI naming guide for getting the primary names right first.
Alias naming conventions
Good aliases follow predictable rules so users can guess them:
- First letters:
create-user→cu. Obvious, but collides fast in large CLIs. - Truncation:
generate-report→gen-report. Readable and guessable. - Common synonyms:
delete→remove,rm;list→ls. - Single letters for the top three: reserve
h,v, and similar only for the most-used commands — single letters are precious namespace.
Pick one convention per CLI and document it. A CLI where some aliases are truncations, some are initials, and some are whimsy is worse than no aliases at all. Generate candidates with the command name generator and filter for collision-free short forms.
Avoiding alias collisions
Every alias must resolve to exactly one command — an ambiguous alias is a bug. Maintain a registry (even a simple table in your docs) mapping every alias to its canonical command, and check new aliases against three collision sources: existing commands, existing aliases, and shell builtins users might expect (ls, rm, cp behave a certain way — hijacking them invites fury). Reserve a namespace for future core commands so today's clever alias does not block tomorrow's feature.
Documenting aliases properly
Undocumented aliases are Easter eggs; documented aliases are features. List aliases in --help output next to their canonical commands, mark deprecated aliases with their removal version, and keep the alias table in your docs next to the command patterns reference. When an alias is retired, do it loudly: one release with a deprecation warning, then removal in a major version — never silent disappearance.
Alias patterns at a glance
| Canonical | Good alias | Why it works |
|---|---|---|
create-user | mkuser | Truncation, still readable |
delete-profile | rm-profile | Synonym users already know |
list-services | ls-svc | Initials of a frequent command |
show-config | config | The obvious guess, claimed deliberately |
old-deploy | deploy (deprecated) | Migration bridge with warning |
Rule of thumb: if users cannot guess the alias, it is a secret handshake, not a shortcut. Document every alias, deprecate loudly, and never let an alias outlive its usefulness silently.
Aliases and shell completions
Aliases should work everywhere the canonical command works — including tab completion. If your CLI generates completions, make sure aliases complete too; an alias you cannot tab-complete is an alias power users will not trust. Test the full matrix: alias alone, alias with flags, alias in scripts. And remember that completions are documentation: when a user tabs through available commands, seeing both delete-profile and its alias rm-profile teaches the shortcut at the moment of need.
FAQ
How many aliases should a command have?
One or two. More than that and users cannot remember which are real; the alias system becomes its own learning burden.
Should aliases appear in --help?
Yes — next to the canonical command. Hidden aliases help nobody except the people who already know them.
Can aliases have their own flags?
No. An alias is purely a name for the command; flags belong to the canonical command. Aliases that behave differently are not aliases — they are undocumented features.
How do I retire an alias safely?
Deprecation warning in one minor release ("alias X is deprecated, use Y"), removal in the next major. Scripts depending on it get a full cycle to migrate.
Should single-letter aliases be avoided?
Reserve them for the two or three most-used commands. Single letters are the scarcest namespace in a CLI — spend them where the frequency justifies it.