DEV Community: jib2004

Building a CLI tool with Python(Click)

jib2004 — Mon, 03 Aug 2026 22:52:00 +0000

Not every useful tool needs a web interface, a database server, or a login page. Sometimes the fastest way to solve a problem is a small command-line tool you can run from your terminal in two seconds. That's exactly what I built with Penny a lightweight command-line expense tracker written in Python, powered by the Click library.

Penny lets you add expenses, list them, see a spending summary by category, and clear everything out all from the terminal, with no external database, no server, and no setup beyond installing one dependency. In this post, I'll walk through exactly how it works, file by file, and explain the Click concepts that make it all click.

Why Click?

Python's built-in argparse module can build command-line tools too, but it gets verbose fast. Click takes a different approach: you write regular Python functions and decorate them with @click.command() and @click.option(), and Click handles all the parsing, help text, and validation for you.

The result is CLI code that reads almost like plain Python, which is exactly what you'll see in Penny's commands.py.

Project Structure

Penny is organized into three main pieces:

penny/
├── commands.py # Each command's logic
├── penny.py # Groups the commands into one CLI
└── pyproject.toml # Packaging + entry point config

This separation matters: commands.py defines what each command does, while penny.py defines how they're exposed together as a single penny command. Let's go through each one.

commands.py: Where the Logic Lives
Reading and writing expenses as JSON

Penny doesn't use a database it stores everything in a simple expenses.json file, where each expense is a dictionary with an amount, category, and note:

expense_file = Path("expenses.json")

Every command opens this file, reads the existing list of expenses with json.load(), does something with it, and for commands that change data writes it back with json.dump(). This is a pattern you'll see repeated across almost every command: read the JSON, modify it in Python, write the JSON back.

The add command

@click.command()
@click.option("--amount", type=int, default=0)
@click.option("--category", default="")
@click.option("--note", default="")
def add(amount, category, note):
        if not expense_file.exists():
        file_path = dir_path / expense_file
        file_path.touch(exist_ok=True)
        expense_file.write_text("[]")

    with open("expenses.json","r") as f:
        expenses = json.load(f)

    expenses.append({"amount":amount,"category":category,"note":note})
    with open("expenses.json","w") as f:
        json.dump(expenses,f,indent=4)


    click.echo( click.style("Added expense",fg="green"))

Each @click.option() decorator turns a function argument into a command-line flag. This means running:

bash

penny add --amount 25 --category food --note "lunch"

calls add(amount=25, category="food", note="lunch") automatically. Click handles converting --amount into an actual integer because of type=int, and supplies sensible defaults if a flag is skipped.

Inside the function, if expenses.json doesn't exist yet, it's created and initialized with an empty list ("[]"). Then the new expense is appended to the list and the whole thing is saved back to disk.

Finally, click.echo(click.style("Added expense", fg="green")) prints a colored confirmation message one of Click's nice built-in touches: click.style() lets you add terminal colors without pulling in a separate library.

The list command

@click.command()
def list():
    ...

This command loads all saved expenses and prints them in a simple table format, using nl=False to keep multiple click.echo() calls on the same line, and nl=True on the last one to move to a new line:

click.echo(f"{expense['amount']}    ", nl=False)
click.echo(f"{expense['category']}    ", nl=False)
click.echo(f"{expense['note']}    ", nl=True)

If there are no expenses yet, it prints a red warning instead (click.style("No expenses added", fg="red")) and exits early using exit(0).

The summary command

@click.command()
def summary():
    ...

This is where the tool becomes genuinely useful. It loops through every expense, tracks the amount per category in a dictionary, and uses functools.reduce() to add up the total:

total_amount = reduce(lambda x, y: x + y, amt, 0)

reduce() here is just a compact way of summing a list equivalent to using sum(amt), but it's a nice demonstration of functional-style Python. The category totals and the grand total are then combined into one dictionary and printed as formatted JSON:

click.echo(json.dumps(summary_note, indent=4))

The clear command

@click.command()
def clear():
    if click.confirm("Are you sure you want to delete all expenses?"):
        ...

This one demonstrates another handy Click feature: click.confirm(), which prompts the user with a yes/no question and only proceeds if they confirm. It's a small safety net before wiping out expenses.json by overwriting it with an empty list.

penny.py: Tying the Commands Together

@click.group()
def cli():
    pass

cli.add_command(command.add)
cli.add_command(command.list)
cli.add_command(command.summary)
cli.add_command(command.clear)

This is where Click's group concept comes in. A @click.group() acts as a parent command that individual subcommands attach to. Once everything is registered, users interact with one unified tool:

bash
penny add --amount 40 --category transport --note "bus fare"
penny list
penny summary
penny clear

Each of those is really just calling the matching function back in commands.py, but from the user's perspective, it feels like one polished CLI application with multiple built-in features not four separate scripts.

pyproject.toml: Making It Installable
toml
[project.scripts]
penny = "penny.penny:cli"

This line is what turns Penny from "a Python file you run with python penny.py" into an actual installed command you can type as penny from anywhere in your terminal. Combined with flit_core as the build backend, this config allows the whole tool to be installed with a simple pip install ., after which penny becomes available as a real command just like git or ls.

What I Learned Building This

A few things stood out while building Penny:

Click decorators remove a lot of boilerplate. Compare @click.option("--amount", type=int) to manually parsing sys.argv Click's declarative style is dramatically less error-prone.
JSON is a perfectly fine "database" for small tools. For a single-user CLI tracking a personal list of expenses, there's no need for SQLite or Postgres a JSON file does the job with zero setup.
Small UX details matter. Things like colored output (click.style) and confirmation prompts (click.confirm) make a CLI tool feel considered rather than thrown together.
Grouping commands makes a tool feel like a real product. The jump from "a script" to "a CLI application" really happens at the @click.group() step, where scattered functions become one cohesive interface.

Learning Python

jib2004 — Sun, 26 Jul 2026 10:39:21 +0000

I started learning Python with CS50 Harvard's Introduction to Programming with Python and honestly, it wasn't part of some grand plan. I've tried a few scattered tutorials before, the kind that show you print("hello world") and then jump straight into building an app three minutes later, leaving me more confused than when you started. CS50 was different. It's completely free on YouTube, taught by David Malan, and it felt less like a tutorial and more like actually sitting in a real classroom mistakes, live debugging, audience questions and all.
This post is my personal walk-through of the course, week by week, topic by topic. Not a syllabus copy-paste just what each concept actually felt like to learn, where I got stuck, and what finally made things click. If you're thinking about starting CS50 yourself, I hope this gives you an honest picture of the road ahead.

Functions and Variables Where I Actually Started
The first lecture is where I learned that a "function" is basically an action, and a "variable" is just a labeled box for storing something. That sounds simple written out like that, but sitting there for the first time, even print() and input() felt like a small victory.

def main():
    name = input("What's your name? ")
    hello(name)

def hello(name):
    print(f"hello, {name}")

main()

I remember writing my own function for the first time and feeling like I'd unlocked something. It wasn't just about using tools someone else built I was building my own small piece of logic, even if it was tiny.

Conditionals My First "Aha" Moment
Conditionals were the first time programming started to feel like actual thinking instead of memorizing syntax. if, elif, else suddenly my code could react to different situations instead of just running the same way every time.

if(n%4 == 0 and n % 100 != 0 or n % 400 == 0):
    print("This is a leapYear")
else:
    print("This is not a leapYear")

I'll be honest, I messed up indentation more times than I'd like to admit here. But this was the week I stopped seeing Python as "commands to memorize" and started seeing it as logic I could actually reason through.

Loops When Things Started Feeling Powerful
Loops were the point where I realized I didn't have to write the same line of code ten times if I wanted something to happen ten times. for loops and while loops felt like a genuine upgrade in what I could build.

 for i  in range(a):
      i+=1
       print("*" * i)
       a -=1

Combining loops with the conditionals I'd just learned was a turning point for me I could suddenly validate input until it was correct, or repeat something until a condition was met. It felt like my toolkit had doubled overnight.

Exceptions Learning to Expect Failure
I used to think errors meant I'd done something wrong and needed to panic. This week reframed that completely. try and except taught me that errors are something you plan for, not something you're supposed to avoid entirely.

def withdraw(balance,amount):
 try:
   if amount > balance:
     raise NameError("Insufficient Balance")
   print(f"Get your amount {amount}")
 except NameError:
   print("Inssuficient Balance")

This was a genuine mindset shift for me from "my code is broken" to "my code needs to handle the moment it breaks."

Libraries Realizing I Didn't Have to Build Everything
I remember feeling almost relieved during this week. I didn't have to reinvent the wheel every time I needed something Python's standard library and third-party packages already had solutions for most common problems.

import  csv

This was also the week I learned to actually read documentation instead of guessing. It's a skill nobody tells you is a "programming skill," but it absolutely is.

Unit Tests The Week I Started Taking My Code Seriously
Before this, I'd just run my code and squint at the output to see if it "looked right." Learning pytest and writing actual assertions changed how I thought about my own work.

Writing my first test felt oddly satisfying like I was finally proving something instead of just hoping it worked.

File I/O Making My Programs Remember Things
Up until this point, everything I built forgot itself the second I closed the program. Learning to read and write files felt like giving my code a memory for the first time.

import  csv

name = input("Enter student name: ")
home = input("Enter home address: ")
with open("students.csv","a") as file:
   writer = csv.DictWriter(file,fieldnames=["name","home"])
   writer.writerow({"name":name,"home":home})

This is also where I learned about the with keyword, and honestly, understanding why it matters (safely closing files automatically) took me longer than actually using it correctly.

Regular Expressions this Week That Humbled Me
I won't pretend this one was easy. Regular expressions felt like learning a second, stranger language stacked on top of Python. Validating something like an email address suddenly required this dense string of symbols that looked like nonsense at first glance.

import re
if re.search(r"^\w+@\w+\.(com|edu|gov|net)$",email,re.IGNORECASE): # \w any word character
   print("Email Address is valid")
else:
   print("Email Address is invalid")

It took rewatching parts of this lecture more than once for it to sink in. If you find regex confusing at first, I can tell you from experience that's a completely normal reaction, not a sign you're behind.

Object-Oriented Programming Where Everything Finally Connected
By the time I reached OOP, something clicked. Classes let me bundle variables and functions together into something that actually resembled a real-world "thing" instead of scattered logic everywhere.

class Student:
   def __init__(self, name, house, pet,age=None):
       self.name = name
       self.house = house
       self.age = age
       self.pet = pet


   def __str__(self):
       return f"{self.name} from {self.house} is {self.age}"


   @property
   def name(self):
       return self._name


   @name.setter
   def name(self,name):
       if not name:
           raise ValueError("Student name cannot be empty")
       self._name = name


   # Getter
   @property # to tell python to treat this as a getter
   def house(self):
       return self._house


   # Setter
   @house.setter #to tell python this is a setter
   def house(self, house):
       if house not in ["Lagos", "Ikoyi", "Yaba"]:
           raise ValueError("Invalid house")
       self._house = house

This was the week I looked back and realized how much everything before it had been building toward this moment. Functions became methods. Variables became attributes. Exceptions and testing suddenly applied to something bigger and more "real" than anything I'd written earlier in the course.