Writing Your First Python CLI with argparse

Sooner or later you write a Python script useful enough that you want to run it with different options instead of editing the code each time. That is the moment to reach for argparse. Building a Python CLI with argparse is one of those skills that feels fiddly for about ten minutes and then becomes second nature you use forever.

Why not just read sys.argv?

You can read arguments straight from sys.argv, but you will end up hand-writing parsing, validation, help text, and error messages — badly. argparse is in the standard library and gives you all of that for free, including a polished --help output that makes your script feel like a real tool.

A minimal example

Here is a complete little CLI that greets someone a number of times:

import argparse

parser = argparse.ArgumentParser(
    description="Greet someone by name.")
parser.add_argument("name",
    help="who to greet")
parser.add_argument("-c", "--count", type=int, default=1,
    help="how many times to greet")

args = parser.parse_args()
for _ in range(args.count):
    print(f"Hello, {args.name}!")

Run it as python greet.py Sam --count 3 and it prints the greeting three times. That is a real, usable command-line program in a dozen lines.

Positional vs optional arguments

Notice the two styles above. name is positional — required, given by position. --count is optional — it has a flag and a default, so the user can leave it out. As a rule, make the essential inputs positional and everything tweakable an option with a sensible default. Your users should be able to run the common case with the fewest words.

The niceties you get for free

Because you declared types and help strings, argparse handles the annoying parts automatically. Pass --count abc and it rejects it with a clear error instead of crashing deep in your loop. Run python greet.py --help and it prints usage and descriptions you never had to format. Flags like store_true give you clean boolean switches:

parser.add_argument("--verbose", action="store_true",
    help="print extra detail")

The takeaway

Whenever a script grows past “edit the variables at the top,” give it a proper interface. Building a Python CLI with argparse takes only a few lines, turns your one-off scripts into reusable tools, and makes them pleasant for other people — and forgetful future-you — to actually run.