Write the CLI help first

Before writing any code for a command-line tool, write its --help output. It is the cheapest design review you will ever get.

Why it works

Help text forces you to name every flag, pick defaults, and explain each one in a sentence. A flag that needs a paragraph is a flag that is doing two things. A command you cannot describe without “and” probably wants to be two commands.

Habits of tools people trust

• Safe by default. Destructive actions want a flag or a confirmation, and a --dry-run.
• Quiet on success, loud on failure. Errors say what happened and what to try next.
• Output for humans and machines. Readable by default, --json when piped into something else.
• Exit codes that mean something. Scripts depend on them more than on any message.
• Idempotent where possible. Running it twice should not be a disaster.

Then keep it honest

Treat the help text as part of the interface: test that it matches the flags the parser accepts. Documentation that drifts from behaviour is worse than none.