How to Turn a Python Script into a CLI Tool Using uv — The Minimal Way

2025-05-26

~5 min read

Want to turn your Python script into a proper command-line tool — with zero boilerplate and ultra-fast dependency management? Here’s a clean and minimal setup using uv, the blazing-fast Python package manager from Astral.

We’ll build a the CLI part of a tool called logcleaner — a simple CLI for cleaning up log files — and install it so you can run it from anywhere on your system.

⚡ Step 1: Create Your Project Folder

Start by creating and entering a folder for your new CLI:

mkdir logcleaner cd logcleaner

mkdir logcleaner
cd logcleaner

⚙️ Step 2: Initialize the Project with uv

Use uv to scaffold a Python project and manage dependencies:

uv init uv add click

uv init
uv add click

This sets up a pyproject.toml for you and installs click, a great library for building CLI interfaces.

🧠 Step 3: Add Your CLI Logic

Create a folder for your code and a main Python file:

Create a folder that contains our source code mkdir logcleaner # Use your favorite editor and create a main.py file inside that folder touch logcleaner/main.py

# Create a folder that contains our source code
mkdir logcleaner

# Use your favorite editor and create a main.py file inside that folder
touch logcleaner/main.py

Paste this minimal logic into logcleaner/main.py:

import click @click.command() @click.option(“–path”, required=True, help=”Path to log file”) @click.option(“–dry-run”, is_flag=True, help=”Simulate cleanup”) def clean(path, dry_run): if dry_run: print(f”[Dry Run] Would clean logs at {path}”) else: print(f”Cleaning logs at {path}…”) if name == “main”: clean()

import click

@click.command()
@click.option("--path", required=True, help="Path to log file")
@click.option("--dry-run", is_flag=True, help="Simulate cleanup")
def clean(path, dry_run):
    if dry_run:
        print(f"[Dry Run] Would clean logs at {path}")
    else:
        print(f"Cleaning logs at {path}...")

if __name__ == "__main__":
    clean()

This tells uv to expose a logcleaner command that runs the clean() function in your main.py.

📝 Step 4: Register the CLI in pyproject.toml

Open pyproject.toml and add the following section at the bottom:

[project.scripts] logcleaner = “logcleaner.main:clean”

[project.scripts]
logcleaner = "logcleaner.main:clean"

✅ Step 5: Install the CLI

Now install your tool so it becomes available as a real command-line program:

uv pip install .

uv pip install .

You can now run it like this:

logcleaner –path /var/log/syslog –dry-run

logcleaner --path /var/log/syslog --dry-run

🛠️ Live Editing with -e

If you want to work on your CLI and instantly reflect changes without reinstalling each time, install it in editable mode :

uv pip install -e .

uv pip install -e .

This keeps the link to your local code, so you can edit and immediately test:

logcleaner –path ./debug.log

logcleaner --path ./debug.log

🚀 That’s It!

You now have a working, installable Python CLI — built and managed with uv, using modern best practices and zero clutter.

Let me know in the comments if you want to see:

• How to use argparse or typer instead of click
• How to publish your tool to PyPI
• How to add unit tests

Happy hacking! 🔧🐍