CLI arguments

Reading from stdin works well when your tool is in a pipeline. But sometimes a user wants to name a file directly, or pass options to change behavior. That is what command-line arguments are for — and argparse is the standard Python library for handling them.

Why not just use sys.argv?

sys.argv gives you the raw list of strings the user typed. You could parse it manually, but you would have to handle errors, write your own --help, and invent a syntax for flags yourself. argparse does all of that for you.

A minimal argparse setup

import argparse

parser = argparse.ArgumentParser(description="Count words in a file.")
parser.add_argument("filename", help="The file to read")
parser.add_argument("--verbose", action="store_true", help="Print extra detail")
args = parser.parse_args()

# args.filename is the string the user passed
# args.verbose is True or False
print("File:", args.filename)
print("Verbose:", args.verbose)

Run this as python counter.py report.txt --verbose and args.filename is "report.txt", args.verbose is True. Run it with no arguments and argparse prints an error message with usage. Run it with --help and argparse prints the full help text — generated automatically from the help= strings you provided.

The --help output looks like this:

usage: counter.py [-h] [--verbose] filename

Count words in a file.

positional arguments:
  filename    The file to read

options:
  -h, --help  show this help message and exit
  --verbose   Print extra detail

You wrote none of that manually. It came from the description=, help=, and argument definitions.

Try it

The browser runner does not support sys.argv, so this demo calls parse_args() with an explicit list — the same values that would come from the command line in a real terminal:

Common patterns

Where to go next

Next: exit codes and errors — what exit codes are, when to use them, and why a program that exits 0 on failure is dangerous in a pipeline.