How do you give an argparse CLI git-style subcommands and dispatch to the right handler?

### The shape argparse gives you A subcommand CLI — `tool build`, `tool clean`, in the style of version-control and package tools — is built from *nested parsers*. `parser.add_subparsers()` is called once on the top-level parser and returns a special action object. Calling `add_parser("build")` on it creates a brand-new `ArgumentParser` dedicated to that subcommand, which you then configure exactly like any other parser: its own `add_argument()` calls, its own `help=` and `description=`, its own auto-generated `-h`. The top-level `-h` lists the subcommand names; `tool build -h` prints the build parser's own help. ### Knowing which subcommand ran By default nothing on the resulting `Namespace` tells you which subparser matched, so pass `dest="command"` to `add_subparsers()` and the chosen name is stored as `args.command`. Also pass `required=True`: without it, running the tool with no subcommand at all parses successfully and leaves you with a Namespace that has no command, which turns a user mistake into an `AttributeError` deep in your code. With `required=True` argparse prints the usage line and `error: the following arguments are required: command`, exiting with status 2 like every other parse failure. ### Dispatching without an if/elif ladder The idiom worth learning is `set_defaults()`. Each subparser can inject arbitrary values into the Namespace, including a function object: `build_parser.set_defaults(func=run_build)`. After parsing, the whole dispatch is `args.func(args)`. This keeps each subcommand's declaration and its implementation next to each other, removes a chain that grows with every command, and makes adding a subcommand a purely additive change. The handlers take the Namespace so they see both their own arguments and the global ones. A variant passes `**vars(args)` into a handler with matching keyword parameters — cleaner signatures, but it breaks the moment a global argument is added that a handler does not accept, so the Namespace-in form travels better. ### Where global options live An argument declared on the top-level parser is only recognised **before** the subcommand name, because once argparse matches a subcommand it delegates the remainder of the command line to that subparser. So `report --verbose build` works while `report build --verbose` fails, unless `--verbose` is also declared on the build subparser. Users routinely type the second form, so the usual fix is to declare shared options once in a separate `ArgumentParser(add_help=False)` and pass it as `parents=[common]` to the top-level parser and to every subparser; `add_help=False` matters, or the two `-h` definitions collide. That fix has a sharp edge worth knowing about. The subparser is parsed after the top-level parser and writes its own results onto the shared Namespace, so a flag given *before* the subcommand is then overwritten by the subparser's own default: with a plain `store_true` on both, `report --verbose build` comes back with `verbose=False`. Give the shared option `default=argparse.SUPPRESS` and the subparser stores nothing when the flag is absent, leaving the earlier value intact; because the attribute is then missing when nobody passed the flag, read it as `getattr(args, "verbose", False)`. The alternative is to keep global options genuinely global, document that they precede the subcommand, and never duplicate them. ### Sizing and naming Subcommands earn their keep when the operations genuinely take different arguments; if every command takes the same three options, a single parser with a `choices=` argument is simpler and its `-h` is one screen instead of many. `add_parser()` accepts `aliases=["ls"]` for short forms, and `help=` (shown in the top-level listing) is separate from `description=` (shown in the subcommand's own help), which is a distinction people get wrong and then wonder why the parent listing is blank. Subparsers nest arbitrarily — a subparser can call `add_subparsers()` itself — but two levels is already a lot to ask of a user's memory. ### Testing the thing Because `parse_args()` accepts an explicit list, a subcommand CLI is straightforward to test without touching the process argument list: `parser.parse_args(["build", "--rows", "6800"])` returns a Namespace you can assert on, and the `func` default lets you assert that the right handler was selected rather than executing it. Build the parser in a function that returns it, and keep the top-level entry point down to building, parsing and calling `args.func(args)` — that function is then reusable from tests, from another program, and from the module's own `__main__` guard, and nothing about the CLI's structure depends on the process actually being started from a shell.