1. Why Build CLI Tools?

Command-line tools embody simplicity and speed. They integrate directly into the developer’s workflow, automate repetitive actions, and often become the hidden backbone of modern software projects. Unlike web apps, CLIs are interfaces of intention — fast, minimal, scriptable.

“A good CLI is not just functional — it feels like a conversation between engineer and machine.” — redesign.ir

2. Designing Your CLI’s Soul: UX and Purpose

Before writing a single line of code, define what your tool does and how it should feel. Is it playful? Precise? Scriptable? Each command should reflect that personality.

• Keep subcommands consistent (use verbs: init, build, deploy).
• Prefer concise, self-documenting flags like --verbose, --force.
• Always provide --help output with usage examples.

3. Choosing the Right Framework: argparse vs Typer

argparse is the standard library’s robust foundation. It’s perfect for small tools and requires zero dependencies. But for developer experience and scalability, Typer (built on Click) provides type hints, colors, and automatic docs.

import typer

app = typer.Typer()

@app.command()
def greet(name: str, excited: bool = False):
    """Simple greeting command"""
    if excited:
        typer.echo(f"Hello, {name}!!! 🎉")
    else:
        typer.echo(f"Hello, {name}.")

if __name__ == "__main__":
    app()
      

Run your tool with python app.py greet Ragr --excited and feel the instant feedback loop.

4. Structuring Your Project

Adopt a clean project layout early. Here’s a minimal but scalable structure:

.
mycli/
├── mycli/
│   ├── __init__.py
│   ├── main.py
│   └── commands/
│       ├── greet.py
│       └── utils.py
├── tests/
│   └── test_greet.py
├── pyproject.toml
└── README.md
      

This ensures your CLI grows gracefully as you add subcommands or API integrations.

5. Packaging & Distribution with pyproject.toml

Modern Python packaging revolves around pyproject.toml (PEP 621). It defines your metadata, dependencies, and build system:

[project]
name = "mycli"
version = "0.1.0"
description = "A simple, fast CLI example"
authors = [{name="Ragr", email="[email protected]"}]
dependencies = ["typer"]
[project.scripts]
mycli = "mycli.main:app"
      

Now, install locally for testing:

pip install -e .

Your CLI command mycli is now globally available.

6. Testing Your CLI

Use pytest with capsys or typer.testing.CliRunner to simulate terminal behavior. Automated tests ensure every command behaves predictably.

from typer.testing import CliRunner
from mycli.main import app

runner = CliRunner()

def test_greet():
    result = runner.invoke(app, ["greet", "Dragon"])
    assert "Hello, Dragon." in result.stdout
      

7. Automating Releases & Versioning

Once your CLI feels stable, automate releases with GitHub Actions and hatch or setuptools-scm. Continuous integration ensures every push triggers tests and version bumps.

8. Distributing via PyPI or Homebrew

Upload your package securely using twine:

python -m build
python -m twine upload dist/*

For macOS users, you can also create a Homebrew formula to make installation seamless:

brew install ragr/tools/mycli

9. Bonus: Adding Telemetry and Error Tracking

For professional-grade tools, include anonymous telemetry (e.g., Sentry or PostHog) to understand feature usage and errors — always respecting user privacy.

10. Final Thoughts — CLIs as Living Systems

Building a CLI is a meditation on clarity. Each command, argument, and error message teaches the system how to speak your language. Done right, your tool becomes part of your creative flow — a living extension of your intent.

In the ecosystem of redesign.ir, every script is a spark in the Dragon’s network — pragmatic, poetic, and alive.