Real Python: Build Command-Line Interfaces With Python's argparse

Command-line apps may not be common in the general user’s space, but they’re present in development, data science, systems administration, and many other operations. Every command-line app needs a user-friendly command-line interface (CLI) so that you can interact with the app itself. In Python, you can create full-featured CLIs with the argparse module from the standard library.

In this article, you’ll learn how to:

• Get started with command-line interfaces
• Organize and lay out a command-line app project in Python
• Create command-line interfaces with Python’s argparse
• Deeply customize your CLIs with some powerful features of argparse

To get the most out of this tutorial, you should be familiar with Python programming, including concepts such as object-oriented programming, script development and execution, and Python packages and modules. It’ll also be helpful if you’re familiar with general concepts and topics related to using a command line or terminal.

Getting to Know Command-Line Interfaces

Since the invention of computers, humans have always needed and found ways to interact and share information with these machines. The information exchange has flowed among humans, computer software, and hardware components. The shared boundary between any two of these elements is generically known as an interface.

In software development, an interface is a special part of a given piece of software that allows interaction between components of a computer system. When it comes to human and software interaction, this vital component is known as the user interface.

You’ll find different types of user interfaces in programming. Probably, graphical user interfaces (GUIs) are the most common today. However, you’ll also find apps and programs that provide command-line interfaces (CLIs) for their users. In this tutorial, you’ll learn about CLIs and how to create them in Python.

Command-Line Interfaces (CLIs)

Command-line interfaces allow you to interact with an application or program through your operating system command line, terminal, or console.

To understand command-line interfaces and how they work, consider this practical example. Say that you have a directory called sample containing three sample files. If you’re on a Unix-like operating system, such as Linux or macOS, go ahead and open a command-line window or terminal in the parent directory and then execute the following command:

$ ls sample/
hello.txt     lorem.md      realpython.md

The ls Unix command lists the files and subdirectories contained in a target directory, which defaults to the current working directory. The above command call doesn’t display much information about the content of sample. It only displays the filenames on the screen.

PS> ls .\sample\    Directory: C:\sampleMode                 LastWriteTime         Length Name----                 -------------         ------ -----a---          11/10/2022 10:06 AM             88 hello.txt-a---          11/10/2022 10:06 AM           2629 lorem.md-a---          11/10/2022 10:06 AM            429 realpython.md

Suppose you want richer information about your directory and its content. In that case, you don’t need to look around for a program other than ls because this command has a full-featured command-line interface with a useful set of options that you can use to customize the command’s behavior.

For example, go ahead and execute ls with the -l option:

$ ls -l sample/
total 24-rw-r--r--@ 1 user  staff    83 Aug 17 22:15 hello.txt-rw-r--r--@ 1 user  staff  2609 Aug 17 22:15 lorem.md-rw-r--r--@ 1 user  staff   428 Aug 17 22:15 realpython.md

The output of ls is quite different now. The command displays much more information about the files in sample, including permissions, owner, group, date, and size. It also shows the total space that these files use on your computer’s disk.

This richer output results from using the -l option, which is part of the Unix ls command-line interface and enables the detailed output format.

Commands, Arguments, Options, Parameters, and Subcommands

Throughout this tutorial, you’ll learn about commands and subcommands. You’ll also learn about command-line arguments, options, and parameters, so you should incorporate these terms into your tech vocabulary:

• Command: A program or routine that runs at the command line or terminal window. You’ll typically identify a command with the name of the underlying program or routine.

• Argument: A required or optional piece of information that a command uses to perform its intended action. Commands typically accept one or many arguments, which you can provide as a whitespace-separated or comma-separated list on your command line.

• Option, also known as flag or switch: An optional argument that modifies a command’s behavior. Options are passed to commands using a specific name, like -l in the previous example.

• Parameter: An argument that an option uses to perform its intended operation or action.

• Subcommand: A predefined name that can be passed to an application to run a specific action.

Consider the sample command construct from the previous section: