Python Academy · Lesson

Subcommands and Options

Build complex CLIs.

Subcommands and Options is a free Python Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Python Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Subcommands?

Tools like git have subcommands: git add, git commit. argparse supports this through subparsers, where each subcommand has its own arguments.

import argparse

parser = argparse.ArgumentParser(prog='tool')
sub = parser.add_subparsers(dest='command')
print('subparsers ready')

Adding Subparsers

add_subparsers returns an object whose add_parser method creates each subcommand. dest stores which one was chosen.

import argparse

parser = argparse.ArgumentParser()
sub = parser.add_subparsers(dest='command')
sub.add_parser('start')
sub.add_parser('stop')
args = parser.parse_args(['start'])
print('command:', args.command)

Per-Subcommand Arguments

Each subparser can define its own arguments. The add subcommand here takes a name; list takes none.

import argparse

parser = argparse.ArgumentParser()
sub = parser.add_subparsers(dest='command')
p_add = sub.add_parser('add')
p_add.add_argument('name')
sub.add_parser('list')
args = parser.parse_args(['add', 'milk'])
print(args.command, args.name)

Dispatching on the Command

After parsing, branch on args.command to run the right logic.

import argparse

parser = argparse.ArgumentParser()
sub = parser.add_subparsers(dest='command')
p_add = sub.add_parser('add')
p_add.add_argument('item')
sub.add_parser('clear')

args = parser.parse_args(['add', 'eggs'])
if args.command == 'add':
    print('adding', args.item)
elif args.command == 'clear':
    print('clearing all')

set_defaults for Handlers

A clean pattern attaches a function to each subparser with set_defaults(func=...), then calls args.func(args).

import argparse

def do_hi(args):
    print('hi', args.who)

parser = argparse.ArgumentParser()
sub = parser.add_subparsers()
p = sub.add_parser('hi')
p.add_argument('who')
p.set_defaults(func=do_hi)

args = parser.parse_args(['hi', 'Ana'])
args.func(args)

Shared Options via Parents

A parent parser holds options common to several subcommands, avoiding repetition. Pass parents=[base] and add_help=False.

import argparse

base = argparse.ArgumentParser(add_help=False)
base.add_argument('--verbose', action='store_true')

parser = argparse.ArgumentParser()
sub = parser.add_subparsers(dest='cmd')
sub.add_parser('run', parents=[base])
args = parser.parse_args(['run', '--verbose'])
print(args.cmd, args.verbose)

Default Values per Option

Subcommand options can have their own defaults and types, just like top-level arguments.

import argparse

parser = argparse.ArgumentParser()
sub = parser.add_subparsers(dest='cmd')
p = sub.add_parser('scale')
p.add_argument('--factor', type=float, default=1.0)
args = parser.parse_args(['scale'])
print('factor:', args.factor)

Appending Repeated Options

action='append' lets a flag be given multiple times, gathering each value into a list.

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--tag', action='append', default=[])
args = parser.parse_args(['--tag', 'a', '--tag', 'b'])
print(args.tag)

Counting Flags

action='count' counts how many times a flag appears, the classic -vvv verbosity pattern.

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('-v', action='count', default=0)
args = parser.parse_args(['-v', '-v', '-v'])
print('verbosity level:', args.v)

A Two-Command Tool

Combining subcommands, handlers, and shared options yields a structured multi-command CLI.

import argparse

def add(args):
    print('add', args.item, 'qty', args.qty)

def remove(args):
    print('remove', args.item)

parser = argparse.ArgumentParser()
sub = parser.add_subparsers()
pa = sub.add_parser('add')
pa.add_argument('item')
pa.add_argument('--qty', type=int, default=1)
pa.set_defaults(func=add)
pr = sub.add_parser('remove')
pr.add_argument('item')
pr.set_defaults(func=remove)

args = parser.parse_args(['add', 'pen', '--qty', '3'])
args.func(args)

Required Subcommand

Set required=True on the subparsers so the user must choose a command, otherwise argparse errors out.

import argparse

parser = argparse.ArgumentParser()
sub = parser.add_subparsers(dest='cmd', required=True)
sub.add_parser('go')
args = parser.parse_args(['go'])
print('chosen:', args.cmd)

Quick Check

Test your understanding of subcommands and options.

Recap

You learned subcommands and options:

add_subparsers and add_parser build multi-command tools.
set_defaults(func=...) dispatches to handlers.
Parent parsers share common options.
append and count actions handle repeated flags.

Next: the Click library for decorator-based CLIs.

Frequently asked questions

Is the “Subcommands and Options” lesson free?

Yes — the full text of “Subcommands and Options” is free to read here on the web, and the Python Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Python Academy course, upgrade to CoddyKit PRO.

What will I learn in “Subcommands and Options”?

Build complex CLIs. You practise Python Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Python Academy?

No prior experience is required. Python Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Subcommands and Options” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Python Academy lesson?

Yes. Every Python Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Python Academy