cli

Prefer flags over positional arguments since they are self-documenting and order-independent. Use standard names like -h/--help, -f/--force, and --json, reserve short flags for frequent operations, and never accept secrets via flags because they leak through ps and shell history.

Help text should lead with realistic example invocations, list common commands and flags before the exhaustive list, and include a repo or website link. Running the command with no arguments should show concise help rather than an error or a hang.

Yes, the guidelines apply to any argument-parsing library including yargs, commander, clap, cobra, click, and argparse. The recommendations cover conventions these libraries implement, such as help generation, exit codes, and flag ordering.

Color and animations must be disabled when stdout is not a TTY, when NO_COLOR is set, when TERM=dumb, or when --no-color is passed. Emitting escape sequences into piped output corrupts downstream parsing, so tools should detect TTY status and emit clean data.

Precedence from highest to lowest is: flags, environment variables, project-level config, user-level config in ~/.config/, then system-wide config in /etc/. Tools should follow the XDG Base Directory Specification rather than placing dotfiles directly in $HOME.

Confirmation should scale with severity: minor local changes need none, major remote changes should prompt with an optional dry-run preview, and irreversible deletion should require typing the resource name or a dedicated flag. Prompts only appear when stdin is a TTY.