I Built a Python CLI Toolbox Instead of Writing One-Off Scripts
A former Node developer turned his freeCodeCamp Python certification into a practical CLI toolbox. Using uv for dependency management and argparse for command parsing, he built utilities for CSV‑Excel conversion, image manipulation, and PDF compression, including a rasterization fallback for stubbo…
After completing a freeCodeCamp Python certification, a developer with a Node.js background decided to move beyond one‑off scripts and create a reusable command‑line toolbox. The result is a small Python CLI that handles common file tasks—converting CSVs to Excel, applying image filters, and compressing PDFs—while keeping the code organized and easy to extend.
Why a Toolbox Makes Sense
Every time the author asked an AI assistant to perform a quick task, the assistant returned a short Python script. The script worked, was used once, and then disappeared. Instead of repeating this pattern, the author asked himself: why not build a single, maintainable toolbox that can be reused across projects? The toolbox became a practical way to apply the skills learned in the certification and to bridge the gap between Node and Python development practices.
Getting Started with uv
Package management was the first hurdle. In Node, developers install packages with npm install, track dependencies in package.json, and lock versions in package-lock.json. Python traditionally uses pip and a requirements.txt file, which feels manual and error‑prone. The author discovered uv, a modern Python tool that unifies project creation, dependency handling, virtual environments, and lockfile generation. Commands such as uv init and uv add mirror npm’s workflow, while uv sync ensures that anyone cloning the repository gets an identical environment. This familiarity reduced friction and made the transition smoother.
Project Structure and Argument Parsing
The toolbox follows a clear layout:
src/toolbox/commands/– individual command modulessrc/toolbox/utils/– shared helper functionstests/– test suitepyproject.tomlanduv.lock– project metadata and lockfile
For parsing arguments, the author relied on the standard library’s argparse instead of a full framework. Each command creates its own subparser, defining positional arguments, optional flags, defaults, and type coercion. This approach keeps the code lightweight and avoids unnecessary dependencies.
Key Utilities
The toolbox includes three main categories of utilities:
- CSV ↔ Excel – Uses Python’s
csvmodule for reading andopenpyxlfor writing Excel files. The command validates input and output paths, generating a sensible filename if none is provided. - Image Operations – Built with
Pillow, the commands can convert images to grayscale, apply Gaussian blur, or compress them. Output paths are optional; the tool automatically appends a suffix to the original filename. - PDF Compression – The most interesting feature. The command first attempts standard compression. If the file size does not reduce, it offers a rasterization fallback: each page is rendered to an image, compressed, and then reassembled into a new PDF. This process uses
PyMuPDFfor rendering andPillowfor image handling. Rasterization sacrifices searchable text for a smaller file size, so the tool suggests it only when necessary.
Testing and Packaging
Tests are written with pytest and cover the happy paths for each command. While there is room to add tests for edge cases—invalid paths, unsupported formats, corrupted files—the existing suite provides confidence when refactoring code. Packaging the toolbox as a real CLI is straightforward with uv tool install, after which the command can be run from any terminal: toolbox grayscale image.png.
Takeaways
1. uv brings Python package management in line with modern JavaScript tooling, easing the learning curve for Node developers. 2. argparse is sufficient for building functional command‑line interfaces without extra frameworks. 3. A thoughtful CLI should make smart decisions for the user, such as offering rasterization only when normal compression fails. 4. Even a small, focused project can teach valuable lessons about project structure, dependency handling, and user‑centric design.
In sum, the toolbox demonstrates that a learning project doesn’t need to be complex to be useful. By consolidating repetitive scripts into a single, well‑structured CLI, the author created a reusable tool that can grow with future needs.
Why it matters
A reusable CLI saves time and reduces errors by avoiding repeated scripting, while the use of modern tooling like uv aligns Python development with familiar JavaScript practices, making the learning curve gentler for cross‑language developers.
Key points
- uv simplifies Python package management like npm
- argparse suffices for robust command‑line parsing
- PDF rasterization is a practical fallback for stubborn size limits
- Reusable tools reduce repetitive scripting and improve consistency
Frequently asked questions
What is uv and why use it?
uv is a modern Python project manager that handles virtual environments, dependencies, and lockfiles, mirroring npm’s workflow for easier adoption by Node developers.
How does the PDF rasterization work?
The tool renders each PDF page to an image, compresses the image, converts it back to PDF, and stitches the pages together, sacrificing text searchability for a smaller file.
Can I add more commands to the toolbox?
Yes, simply add a new module in the <code>commands</code> folder and register its subparser in <code>src/toolbox/__init__.py</code>.
