DEV Community: sam jha

5 Python CLI Patterns I Use in Every Project (With Real Code)

sam jha — Thu, 19 Mar 2026 17:30:21 +0000

After building Folder Intelligence — a Python CLI that reads file contents to organize them — I've refined a set of patterns I now use in every project. These aren't fancy abstractions. They're practical building blocks that make CLIs feel professional and maintainable.

Here are the 5 patterns, with real code from my projects.

1. Rich Progress Bars Instead of `print()`

The first thing users notice about your CLI is feedback. Bare print() calls feel amateurish. The rich library makes it trivial to add beautiful progress output.

from rich.progress import Progress, SpinnerColumn, TextColumn
from rich.console import Console

console = Console()

def process_files(files):
    with Progress(
        SpinnerColumn(),
        TextColumn("[progress.description]{task.description}"),
        transient=True,
    ) as progress:
        task = progress.add_task("Processing files...", total=len(files))
        for f in files:
            do_something(f)
            progress.advance(task)
    console.print("[bold green]Done![/bold green]")

This pattern shows real-time progress without flooding the terminal. The transient=True clears the bar when done, leaving a clean output.

2. `--dry-run` Mode From Day One

Every CLI that modifies files, databases, or APIs should have a dry-run mode. It builds trust with users and makes testing 10x easier.

import click

@click.command()
@click.option('--dry-run', is_flag=True, help='Preview changes without applying them')
def organize(dry_run):
    for file in get_files():
        new_name = generate_name(file)
        if dry_run:
            click.echo(f"Would rename: {file} -> {new_name}")
        else:
            file.rename(new_name)
            click.echo(f"Renamed: {file} -> {new_name}")

This is the single most-requested feature after releasing Folder Intelligence. Ship it on day one.

3. JSON Audit Logs for Every Destructive Operation

If your CLI moves, renames, or deletes anything, write an audit log. Users need a way to review (and potentially undo) what happened.

import json
from datetime import datetime
from pathlib import Path

def write_audit_log(operations: list[dict], output_dir: Path):
    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
    log_file = output_dir / f"audit_{timestamp}.json"

    with open(log_file, 'w') as f:
        json.dump({
            "timestamp": timestamp,
            "operations": operations,
            "total": len(operations)
        }, f, indent=2)

    return log_file

# Usage
ops = []
for old, new in renames:
    ops.append({"action": "rename", "from": str(old), "to": str(new)})
    old.rename(new)

log = write_audit_log(ops, output_dir)
print(f"Audit log written: {log}")

This pattern has saved me multiple times during testing. JSON is readable, diffable, and easy to parse for an undo script later.

4. Graceful Error Handling with Context

Nothing is more frustrating than a CLI that throws a raw traceback at you. Catch errors where they happen and give context about what failed.

from rich.console import Console

console = Console()

def process_file(filepath):
    try:
        content = extract_text(filepath)
        new_name = generate_name(content)
        return new_name
    except PermissionError:
        console.print(f"[yellow]Skipped {filepath.name}: no read permission[/yellow]")
        return None
    except Exception as e:
        console.print(f"[red]Error processing {filepath.name}: {e}[/red]")
        return None

The key is: never crash the whole pipeline because one file failed. Log it, skip it, continue.

5. Configuration via Both CLI Args and a Config File

Power users want to set defaults without typing flags every time. The pattern I use: CLI args override config file, which overrides built-in defaults.

import click
import json
from pathlib import Path

def load_config() -> dict:
    config_path = Path.home() / '.folder-intelligence' / 'config.json'
    if config_path.exists():
        return json.loads(config_path.read_text())
    return {}

@click.command()
@click.option('--output-dir', default=None, help='Output directory')
@click.pass_context
def run(ctx, output_dir):
    config = load_config()
    # CLI arg > config file > default
    final_output = output_dir or config.get('output_dir') or './organized'
    process(final_output)

This makes your CLI usable for both quick one-offs and automated pipelines.

Putting It All Together

These patterns are all used in Folder Intelligence — a CLI that reads PDFs, Word docs, and images (via OCR) and organizes them based on their actual content, not just filenames.

If you've found a CLI pattern that you use everywhere, drop it in the comments — I'm always looking to improve the toolbox.

GitHub: https://github.com/SGajjar24/folder-intelligence

I built a Python CLI that reads INSIDE your files to organize them — here's how it works

sam jha — Sun, 22 Feb 2026 22:05:03 +0000

Have you ever looked at a folder full of files named scan001.pdf, document_final_FINAL_v3.docx, or IMG_20231105_142233.jpg and thought: "I have absolutely no idea what any of these are"?

I've been there. So I built a tool to fix it.

What is Folder Intelligence?

Folder Intelligence is a Python CLI that doesn't just look at your filenames — it reads the content of your files to understand what they actually are, then organizes them intelligently.

GitHub: https://github.com/SGajjar24/folder-intelligence

Instead of renaming files based on metadata or patterns, it:

Extracts text from PDFs, Word docs, images (via OCR), and more
Generates meaningful names based on what the file actually contains
Detects and removes duplicate files using SHA-256 hashing
Creates an audit report of everything it did

The Core Problem It Solves

Most file organizers are dumb — they sort by extension, date, or size. They can't tell you that scan001.pdf is actually your 2022 tax return, or that IMG_0042.jpg is a receipt from last year.

Folder Intelligence reads the content and acts on it.

Key Features

1. Content-Aware Renaming

The tool extracts text from files and generates descriptive names:

before: scan001.pdf
after:  2022_tax_return_w2_form.pdf

2. OCR for Images

Using Tesseract OCR, it reads text from scanned documents and images:

before: IMG_20231105.jpg
after:  invoice_amazon_order_receipt.jpg

3. SHA-256 Deduplication

Finds exact duplicates regardless of filename and removes them safely:

Found 3 duplicates (47.2 MB freed)

4. Audit Trail

Every action is logged so you can review (or undo) changes:

audit_report_2024-01-15.json

5. Safe Dry-Run Mode

Run it first with --dry-run to preview all changes before anything gets touched.

Quick Start

pip install folder-intelligence

# Audit your folder
folder-intelligence audit /path/to/folder

# Rename files based on content
folder-intelligence rename /path/to/folder

# Find and remove duplicates
folder-intelligence dedupe /path/to/folder

# Run everything
folder-intelligence pipeline /path/to/folder

Tech Stack

Python 3.8+
PyMuPDF — PDF text extraction
python-docx — Word document parsing
Tesseract OCR — Image text recognition
SHA-256 — Duplicate detection
Rich — Beautiful CLI output

Why I Built This

I was cleaning up 10+ years of accumulated files — downloads, scans, backups — and realized I was spending more time figuring out what a file was before I could organize it than actually organizing it.

Every existing tool I found was either too simple (sort by date) or required cloud AI (expensive, privacy concerns). I wanted something local, fast, and smart.

So I built Folder Intelligence: enterprise-grade file organization, no AI models required, runs 100% offline.

What's Next

[ ] GUI wrapper (Tkinter/PyQt)
[ ] Plugin system for custom file handlers
[ ] Smarter rename suggestions with local LLM support (optional)
[ ] Windows Explorer / macOS Finder context menu integration

Try It Out

GitHub: https://github.com/SGajjar24/folder-intelligence
Star it if you find it useful!
Issues and PRs are very welcome

I'd love feedback from the dev.to community — especially on the rename logic and any edge cases you'd throw at it. What file types or workflows would make this more useful for you?