Introduction

A CLI tool (Command-Line Interface tool) is a program you run and control entirely from the terminal. Great CLI tools are fast, scriptable, and composable — they do one job well, accept arguments and flags, produce clean output, and return proper exit codes so they can be chained together. This guide walks you through building a real CLI tool in Python: structuring the code, parsing arguments, handling errors, and packaging it so others can install and run it as a first-class command.

Real-World Analogy

Prerequisites

Anatomy of a Good CLI Tool

Step 1: A Minimal CLI Tool

Start with a clean structure — logic in functions, a main(), and a guarded entry point.

# greet.py
import argparse
import sys

def greet(name, times):
    for _ in range(times):
        print(f"Hello, {name}!")

def main():
    parser = argparse.ArgumentParser(description="Greet someone")
    parser.add_argument("name", help="who to greet")
    parser.add_argument("-n", "--times", type=int, default=1, help="how many times")
    args = parser.parse_args()

    greet(args.name, args.times)
    return 0

if __name__ == "__main__":
    sys.exit(main())

$ python greet.py Rumman -n 2
Hello, Rumman!
Hello, Rumman!

Step 2: Add Subcommands

Real tools often have multiple actions (git-style). Use subparsers to organize them.

# todo.py
import argparse
import sys

def add(args):
    print(f"Added task: {args.task}")

def remove(args):
    print(f"Removed task: {args.task}")

def main():
    parser = argparse.ArgumentParser(prog="todo")
    sub = parser.add_subparsers(dest="command", required=True)

    add_p = sub.add_parser("add", help="add a task")
    add_p.add_argument("task")
    add_p.set_defaults(func=add)

    rm_p = sub.add_parser("remove", help="remove a task")
    rm_p.add_argument("task")
    rm_p.set_defaults(func=remove)

    args = parser.parse_args()
    args.func(args)      # dispatch to the chosen subcommand
    return 0

if __name__ == "__main__":
    sys.exit(main())

$ python todo.py add "Buy milk"
Added task: Buy milk

Step 3: Handle Errors and Exit Codes

Fail gracefully with a clear message and a non-zero exit code.

import sys

def read_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"Error: file not found: {path}", file=sys.stderr)
        sys.exit(1)      # non-zero = failure

def main():
    content = read_file("data.txt")
    print(content)
    return 0

Step 4: Play Nicely with stdin/stdout/stderr

Composable tools read from stdin, write results to stdout, and send errors to stderr.

import sys

def main():
    # Read piped input if no file given
    data = sys.stdin.read()
    # Normal output -> stdout
    print(data.upper())
    # Diagnostics -> stderr (won't pollute piped output)
    print("Processed input", file=sys.stderr)
    return 0

if __name__ == "__main__":
    sys.exit(main())

$ echo "hello" | python upper.py
HELLO

Step 5: Package It as an Installable Command

Use a pyproject.toml with an entry point so users can run your tool by name.

# pyproject.toml
[project]
name = "mytool"
version = "1.0.0"

[project.scripts]
mytool = "mytool.cli:main"   # command -> module:function

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

$ pip install .
$ mytool Rumman -n 2      # now it's a real command!
Hello, Rumman!
Hello, Rumman!

CLI Framework Options

The Unix Philosophy, Quantified

Small composable tools multiply your power. If you have \(t\) single-purpose tools that can be piped together, the number of possible two-stage pipelines is:

\[ N_{\text{pipelines}} = t \times (t - 1) \]

This combinatorial reuse is why "do one thing well" beats one giant monolithic program — each new small tool multiplies what's possible.

Best Practices

Common Mistakes

Interview Questions

Quick Revision