cli-guidelines-resources-05

Well-designed arguments and flags reduce confusion by using consistent long and short forms, clear boolean flags with --no- prefixes for negations, and explicit help text. Establish ordering conventions, document defaults, and distinguish between positionals, optional flags, and multi-value arguments so users understand what each parameter does.

Positional arguments are required values passed in order; optional flags are named parameters prefixed with -- or - that users can omit; multi-value arguments accept repeated or space-separated inputs. Combining them clearly—with consistent naming and help text—prevents misinterpretation and wrong usage patterns.

Use consistent naming conventions with both forms available: short flags (-f) for frequent use and long flags (--flag-name) for clarity. Apply the same pattern across all commands, document both forms in help text, and use kebab-case for long flags to maintain readability and predictability.

Use --no- prefixes for negations of default-true behaviors to reduce flag count and clarify intent. For example, --no-cache disables caching more explicitly than a separate --cache-disabled flag, making the CLI surface smaller and more intuitive for users familiar with standard conventions.

Document clear ordering rules, use named flags (--name value) instead of relying on position, mark required versus optional arguments, and provide consistent help text. Positional arguments should follow a predictable sequence; optional flags work in any order, reducing user errors from positional confusion.

Define defaults explicitly in help text so users know what happens when they omit a flag. Display the default value in documentation (e.g., --timeout 30s [default: 30]), test that defaults work safely, and ensure flags align with common use cases to minimize the need for users to override them.