Reading a CLI's help text like a contract

A script or an agent that calls a command-line tool depends on its behavior. The help text and man page are where that behavior is written down.

Read the exit status first

Exit codes are the answer a script reads. The GNU grep manual says the status is 0 if a line is selected, 1 if none were, and 2 if an error occurred. With -q, a selected line gives 0 even if an error occurred. A script that treats any non-zero status as failure will misread “no match” as a crash.

The same holds for git diff. Its --exit-code option exits with 1 if there were differences and 0 if there were none. Without that flag, you should not assume the status reports differences.

Check what a flag does not cover

The curl man page says -f, --fail returns error 22 for HTTP responses of 400 or above. It also says the method is not fail-safe, especially with authentication codes 401 and 407. Read the caveats, then test them.

Know the stream and argument rules

The GNU Coding Standards say --help prints brief documentation on standard output and exits successfully. For input, grep reads standard input when no file is given. POSIX conventions say options should precede operands, and that the first -- ends options.

Test before you trust

Run the tool on a match, a miss and a bad input. Check $? each time. Write the results down as the contract your script relies on.