write-cli

Apply systematic CLI design checks before writing or reviewing a command-line tool. Every rule is a concrete yes/no question — answer it, don't rationalize around it.

Signature Shape

1. Flags over positional args. Max 2 positional args, and only when the action is primary and memorable (cp <src> <dst>). Everything else gets --long-name.
2. Full names for every flag. -h always has --help. -v always has --verbose. Short forms are for muscle-memory flags only.
3. No positional args with mixed meanings. If you have cmd <file> <name>, add a third thing, or the second arg means two different things across subcommands — redesign to flags.
4. Order-independent. myapp --verbose subcmd and myapp subcmd --verbose must both work.

Naming

5. Reuse flag names across subcommands. --json means JSON output everywhere. --repo means a repository everywhere. Never use --json on one subcommand and --format json on another.
6. Follow the standard flag table. -a/--all, -d/--debug, -f/--force, -h/--help, --json, --no-input, -o/--output, -p/--port, -q/--quiet, -u/--user, --version. Deviate only with a documented reason.
7. Verb consistency across resource subcommands. Use the same verb set everywhere: list, get, create, update, delete. If one subcommand uses remove and another delete, pick one.

Help & Discovery