Building a CLI Tool

wordstat report myfile.txt                  # basic word/line/char counts
wordstat report myfile.txt --top 5           # the 5 most common words
wordstat report myfile.txt --min-length 4    # ignore words shorter than 4 characters
wordstat --help                               # auto-generated usage help

import argparse

def main():
    parser = argparse.ArgumentParser(description="Analyse word statistics in a text file")
    parser.add_argument("filename", help="Path to the text file to analyse")   # positional — required
    parser.add_argument("--top", type=int, default=10, help="Show the N most common words")

    args = parser.parse_args()

    print(f"Analysing {args.filename}, showing top {args.top} words")

if __name__ == "__main__":
    main()

$ python wordstat.py notes.txt
Analysing notes.txt, showing top 10 words

$ python wordstat.py notes.txt --top 5
Analysing notes.txt, showing top 5 words

$ python wordstat.py
usage: wordstat.py [-h] [--top TOP] filename
wordstat.py: error: the following arguments are required: filename

$ python wordstat.py --help
usage: wordstat.py [-h] [--top TOP] filename

Analyse word statistics in a text file

positional arguments:
  filename    Path to the text file to analyse

options:
  -h, --help  show this help message and exit
  --top TOP   Show the N most common words

import argparse
from collections import Counter

def analyse_file(filename, min_length=1):
    with open(filename, encoding="utf-8") as f:
        text = f.read()

    words = [w.strip(".,!?;:\"'()").lower() for w in text.split()]
    words = [w for w in words if len(w) >= min_length and w]

    return {
        "line_count": text.count("\n") + 1,
        "word_count": len(words),
        "char_count": len(text),
        "most_common": Counter(words).most_common(),
    }

def main():
    parser = argparse.ArgumentParser(description="Analyse word statistics in a text file")
    parser.add_argument("filename", help="Path to the text file to analyse")
    parser.add_argument("--top", type=int, default=10, help="Show the N most common words")
    parser.add_argument("--min-length", type=int, default=1, help="Ignore words shorter than this")

    args = parser.parse_args()

    stats = analyse_file(args.filename, min_length=args.min_length)

    print(f"Lines: {stats['line_count']}")
    print(f"Words: {stats['word_count']}")
    print(f"Characters: {stats['char_count']}")
    print(f"\nTop {args.top} words:")
    for word, count in stats["most_common"][:args.top]:
        print(f"  {word}: {count}")

if __name__ == "__main__":
    main()

def main():
    parser = argparse.ArgumentParser(description="wordstat — a small text analysis tool")
    subparsers = parser.add_subparsers(dest="command", required=True)

    report_parser = subparsers.add_parser("report", help="Full statistics report")
    report_parser.add_argument("filename")
    report_parser.add_argument("--top", type=int, default=10)
    report_parser.add_argument("--min-length", type=int, default=1)

    count_parser = subparsers.add_parser("count", help="Just the total word count")
    count_parser.add_argument("filename")

    args = parser.parse_args()

    if args.command == "report":
        run_report(args)
    elif args.command == "count":
        stats = analyse_file(args.filename)
        print(stats["word_count"])

$ python wordstat.py report notes.txt --top 5
$ python wordstat.py count notes.txt
$ python wordstat.py report --help      # help scoped to just the report subcommand

import sys

def get_text(filename):
    if filename == "-":                # the conventional way to mean "read from stdin"
        return sys.stdin.read()
    with open(filename, encoding="utf-8") as f:
        return f.read()

# Now this works:
# cat notes.txt | python wordstat.py report -

def main():
    parser = argparse.ArgumentParser(...)
    args = parser.parse_args()

    try:
        stats = analyse_file(args.filename)
    except FileNotFoundError:
        print(f"Error: {args.filename} not found", file=sys.stderr)
        sys.exit(1)          # non-zero exit code signals failure to the calling shell/script

    print(f"Words: {stats['word_count']}")
    sys.exit(0)               # explicit, though 0 is also the default if the script just ends normally

if __name__ == "__main__":
    main()

[project]
name = "wordstat"
version = "0.1.0"

[project.scripts]
wordstat = "wordstat.cli:main"     # package.module:function

pip install -e .

wordstat report notes.txt --top 5    # no more "python wordstat.py" needed

A team's deployment process starts as a shared page of copy-pasted shell commands, each engineer running a slightly different variation, with several production incidents traced back to a step run out of order or a flag forgotten entirely. They consolidate the whole process into a single internal CLI tool, built exactly the way this module builds wordstat.

deploytool plan --env staging          # shows what WOULD happen, changes nothing
deploytool apply --env staging          # actually deploys
deploytool apply --env prod --confirm   # --confirm required for prod, on purpose
deploytool rollback --env prod --to v1.4.2

Why this mattered beyond convenience

Every deployment now runs through the exact same validated code path, with argparse itself rejecting malformed invocations before any real action happens — a missing --env, or an attempt to deploy to prod without the deliberately required --confirm flag, fails immediately with a clear error instead of half-executing a copy-pasted shell command with the wrong environment silently baked in. The team's own framing: "the CLI's validation IS the safety mechanism — it is not possible to accidentally deploy to the wrong environment anymore, because the tool simply won't let you."