python-cli-typer
Scannednpx machina-cli add skill narumiruna/agent-skills/python-cli-typer --openclawFiles (1)
SKILL.md
1.7 KB
Python CLI with Typer
Overview
Use Typer for ergonomic CLI construction. Core principle: keep CLI entry points explicit and testable.
Install
uv add typer
Quick Reference
| Task | Pattern |
|---|---|
| Single command | @app.command() |
| Options | function args with defaults |
| Multiple commands | multiple @app.command() |
Workflow
- Define a
typer.Typer()app incli.py. - Keep command functions small; move logic into separate modules.
- Run CLI via
uv run python -m <module>oruv run python cli.py.
Example
import typer
app = typer.Typer()
@app.command()
def greet(name: str, count: int = 1) -> None:
for _ in range(count):
typer.echo(f"Hello, {name}!")
if __name__ == "__main__":
app()
Usage:
uv run python cli.py --help
uv run python cli.py Alice
uv run python cli.py Alice --count 3
Multiple commands:
import typer
app = typer.Typer()
@app.command()
def create(name: str) -> None:
"""Create a new item."""
typer.echo(f"Creating {name}...")
@app.command()
def delete(name: str, force: bool = False) -> None:
"""Delete an item."""
if not force:
if not typer.confirm(f"Delete {name}?"):
raise typer.Abort()
typer.echo(f"Deleted {name}")
if __name__ == "__main__":
app()
Common Mistakes
- Putting heavy business logic inside CLI functions.
- Forgetting to wire
if __name__ == "__main__"for script entry.
Red Flags
- CLI guidance that ignores Typer when Typer is the chosen framework.
Source
git clone https://github.com/narumiruna/agent-skills/blob/main/skills/python-cli-typer/SKILL.mdView on GitHub Overview
This skill teaches building ergonomic CLI tools using Typer in Python. It emphasizes explicit, testable entry points and clear command structures for single-command and multi-command apps, with options defined as function args. Keep CLI logic modular by keeping command functions small and delegating work to separate modules.
How This Skill Works
Create a Typer app with typer.Typer() and decorate functions with @app.command() for each command. Define options as function parameters with defaults; for multi-command apps, register multiple command functions on the same app. Run the CLI via uv run python -m <module> or uv run python cli.py.
When to Use It
- Scaffold a Python CLI with a clear single-command interface and options.
- Add subcommands to manage resources (e.g., create, delete) in one CLI.
- Keep command functions small and move heavy logic to separate modules for testability.
- Rely on Typer's auto-generated help and clean usage output.
- Integrate the CLI as a script/module executed with uv run (e.g., uv run python cli.py).
Quick Start
- Step 1: Install Typer with 'uv add typer'.
- Step 2: Define a Typer app (app = typer.Typer()) and add command functions using @app.command().
- Step 3: Run the CLI with 'uv run python cli.py' or 'uv run python -m <module>'.
Best Practices
- Define a Typer app in a dedicated module (e.g., cli.py) and register commands on it.
- Keep command functions small; delegate business logic to separate modules.
- Include a proper entry point with if __name__ == '__main__' and app() invocation.
- Use function arguments to define Options with sensible defaults.
- Use typer.echo and typer.confirm to interact with users and handle CLI flow.
Example Use Cases
- A greet command that prints Hello, {name}! multiple times using a count option.
- A single-command CLI that shows --help and usage via uv run python cli.py --help.
- A multi-command app with create(name) and delete(name, force=False) commands.
- A delete command that asks for confirmation unless --force is provided.
- Running and testing the CLI by invoking uv run python cli.py Alice or uv run python cli.py Alice --count 3.
Frequently Asked Questions
Add this skill to your agents
