Serguey Asael Shinder: An unknown flag should stop the program, not run it

26 September 2026, 22:10 · by Serguey Asael Shinder / Serguey Shinder

I ran a maintenance script with --help this week, expecting a usage message. It printed nothing useful and then did its normal job: it fetched, staged and wrote files. Nothing was damaged - the job was one it runs on a schedule anyway - but it was not what I had asked for, and the reason is a pattern I see in a lot of internal tooling.

The script parsed its arguments by looking for a handful of known flags. Anything it did not recognise was simply ignored, and when no known flag was present, it fell through to the default action. For a tool whose default action is harmless, that is a curiosity. For a tool whose default action deletes, publishes, migrates or sends, it is an incident waiting for a typo: --dry_run instead of --dry-run, -n on a tool that expects --no-op, or --help on a tool written before anyone thought to add it.

The principle is simple: a tool should fail on input it does not understand, and doing nothing should be what happens by default. In practice that means four things.

• Reject unknown arguments. Every mainstream argument parser does this if you let it - argparse in Python, picocli in Java and most others exit with an error on an unrecognised option. The failure mode appears when someone parses sys.argv by hand with if "--x" in args.
• Make --help and -h always work, and make them exit before any side effect. A tool with no help text should at least treat those flags as "print the list of options and stop".
• Require an explicit verb for destructive work. tool run, tool apply, tool publish - so that the bare command, or a command with only unrecognised flags, prints usage instead of acting.
• Print what you are about to do before doing it, with the resolved options, so that the one time an argument is misread there is a line in the log showing it.

None of this is new advice, and that is the point. Internal scripts are written quickly, by one person, for one job, and they grow into things other people run. The argument handling is the first thing nobody revisits, because it works for the person who wrote it. The cheapest time to make a tool refuse what it does not understand is before the second person uses it.