argparse: Command-Line Arguments in Python

When a script grows from a toy into a real tool, input() becomes inconvenient. Professional CLI programs accept arguments at launch — like git commit -m "fix" or python manage.py migrate. Python has the built-in argparse module for this.

The Problem with input()

# Inconvenient: you have to run it and wait for a prompt
python tool.py
> Enter command: issues
> Enter repository: my-repo

# Convenient: everything in one command
python tool.py issues my-repo
python tool.py issues my-repo --state closed

The second form can be scheduled in cron, called from an automation script, or invoked by another program.

Basic Syntax

import argparse

parser = argparse.ArgumentParser(description="Program description")

# Positional argument (required):
parser.add_argument("repo", help="Repository name")

# Optional argument (with --):
parser.add_argument("--state", default="open", help="Issue state")

args = parser.parse_args()
print(args.repo)    # value from the command line
print(args.state)   # "open" or the provided value

Running:

python tool.py my-repo               # args.repo = "my-repo", args.state = "open"
python tool.py my-repo --state all   # args.state = "all"

Argument Types

# String (default):
parser.add_argument("--query")

# Integer:
parser.add_argument("--days", type=int, default=7)

# True/False flag:
parser.add_argument("--execute", action="store_true")
# python tool.py           → args.execute = False
# python tool.py --execute → args.execute = True

# Restricted set of values:
parser.add_argument("--state", choices=["open", "closed", "all"], default="open")

Subcommands (subparsers)

For complex CLIs with multiple commands, use subcommands — just like git:

parser = argparse.ArgumentParser()
subparsers = parser.add_subparsers(dest="command", help="Command")

# "issues" subcommand:
issues_p = subparsers.add_parser("issues", help="List issues")
issues_p.add_argument("repo")
issues_p.add_argument("--state", choices=["open","closed","all"], default="open")

# "create" subcommand:
create_p = subparsers.add_parser("create", help="Create an issue")
create_p.add_argument("repo")
create_p.add_argument("--title", required=True)
create_p.add_argument("--body", default="")

args = parser.parse_args()

if args.command == "issues":
    # args.repo, args.state are available
    ...
elif args.command == "create":
    # args.repo, args.title, args.body are available
    ...
elif args.command is None:
    parser.print_help()

Running:

python tool.py issues my-repo
python tool.py issues my-repo --state closed
python tool.py create my-repo --title "Bug fix"
python tool.py --help          # auto-generated help
python tool.py issues --help   # subcommand help

Automatic Help

argparse generates --help for free:

$ python tool.py --help
usage: tool.py [-h] {issues,create,close,repos,search} ...

GitHub Automation Tool

positional arguments:
  {issues,create,close,repos,search}
    issues    List repository issues
    create    Create an issue
    ...

options:
  -h, --help  show this help message and exit

required=True and nargs

# Required optional argument:
parser.add_argument("--title", required=True)

# Accepts multiple values:
parser.add_argument("--labels", nargs="+")  # one or more
# python tool.py --labels bug enhancement → ["bug", "enhancement"]

Summary

argparse turns a script into a real CLI tool:
- All parameters are passed at launch, not via input()
- Automatic --help
- Type validation (type=int) and allowed value validation (choices=)
- --execute flags to control behavior
- Subcommands for grouping related commands