auriti-labs/agentwork/python-cli-tooling

Python CLI Tooling

Scope

Building, structuring, testing, and packaging Python CLI tools for distribution.

Triggers

• "create a CLI tool" / "add a command to [tool]"
• "set up pyproject.toml" / "configure entry points"
• "package for pip install" / "publish to PyPI"
• "entry point not found" / "import error in CLI"
• "add --json output" / "add --verbose flag"

When NOT to Use

• Web APIs or HTTP servers
• Python libraries without CLI interface
• Non-Python CLIs (Rust, Go, Node)
• GUI applications

Goals

• Produce a CLI tool that installs cleanly via pip install and runs via its entry point
• Keep CLI layer thin — commands validate input, call core logic, format output
• Ensure the tool works in pipes, scripts, and CI (not just interactive terminals)
• Make every command self-documenting via --help

Constraints

• Always use src/ layout with pyproject.toml (no setup.py)
• Separate CLI layer (cli.py, commands/) from business logic (core/) — one-way dependency only
• Config precedence: CLI flags > env vars > config file > defaults — never hardcode paths
• Use sys.exit(1) for errors, never bare exit() or unhandled exceptions
• Pin minimum dependency versions, not exact: click>=8.0 not click==8.1.7
• Add --verbose, --quiet, --json output flags from the start — retrofitting is painful

Input Minimi

• Tool purpose and target user
• Expected commands and subcommands
• Python version constraint (3.10+, 3.11+, etc.)

Check Before Acting

• pyproject.toml — existing config, dependencies, entry points, build system
• src/ or package directory — existing code structure and naming
• README.md — current usage examples and install instructions
• .github/workflows/ — existing CI/CD for testing and publishing

Checklist

New CLI Tool

1. Choose framework: Typer for simple CLIs, Click for complex ones with plugins (see examples/)
2. Create project structure (see references/project-structure-patterns.md)
3. Define entry point in pyproject.toml under [project.scripts]
4. Implement __main__.py for python -m my_tool support
5. Test: pip install -e . then my-tool --help

Adding a Command

1. Create module in commands/
2. Register in cli.py via decorator or app.add_command()
3. Keep handler thin — validate, call core, format output
4. Add --help text for every parameter

Testing

1. Test CLI invocation with CliRunner (Click) or runner.invoke (Typer)
2. Test core logic independently (no CLI dependency)
3. Test --json output is valid JSON
4. Test exit codes: 0 for success, 1 for user error, 2 for system error
5. See references/testing-and-validation.md for patterns

Packaging

1. See references/packaging-and-release.md for full workflow
2. Quick check: pip install -e . && which my-tool && my-tool --version

Gotchas

1. Entry point not found after `pip install -e .` — The module path in [project.scripts] doesn't match the actual package structure. If your package is src/my_tool/, the entry point is my_tool.cli:app, not src.my_tool.cli:app.

1. Circular imports between CLI and core. CLI imports core, core imports CLI for type hints or decorators. Fix: core must never import from CLI. Use dependency injection or pass callbacks.

1. `--help` shows no commands. Commands are defined but not registered. In Click: forgot @cli.command() or cli.add_command(). In Typer: forgot app.command() decorator or the module isn't imported.

1. Rich output breaks when piped. my-tool | grep something produces ANSI garbage. Fix: check sys.stdout.isatty() and disable color/formatting in non-TTY mode. Or use rich.console.Console(force_terminal=False).

1. Config file not found on other machines. Hardcoded ~/.my-tool/config.yaml. Fix: use pathlib.Path.home() / ".config" / "my-tool" with XDG_CONFIG_HOME fallback, and always handle missing config gracefully.

1. `python -m my_tool` works but `my-tool` command doesn't. The venv isn't activated, or pip install -e . wasn't run after adding the entry point. Always test both invocation methods.

1. Version string out of sync. __version__ in __init__.py says 1.0 but pyproject.toml says 1.1. Fix: use importlib.metadata.version("my-tool") as single source of truth, or use hatch-vcs / setuptools-scm.

1. Subcommand added but tests don't cover it. New command works manually but CI doesn't test it. Fix: every command gets at least one CliRunner test that checks exit code 0 and expected output substring.

1. Renaming or removing a CLI flag breaks downstream scripts. Users and CI pipelines depend on --output-format, you rename it to --format. Fix: keep the old flag as a deprecated alias (@click.option("--output-format", "--format", ...)) and emit a warning. Never remove flags in minor versions.

Handoff

• After CLI structure built → kiro-qa for code review
• After packaging ready → kiro-docs for README and usage guide
• If CLI needs MCP integration → load mcp-integration skill
• If preparing a release → load release-docs-packaging skill

Memory Guidance

TotalRecall: Entry point configurations that worked, project structure decisions, dependency version choices, config precedence patterns Kore candidates: CLI project templates that work across projects, packaging configs that avoid pitfalls, testing patterns for CLI tools Never save: Standard Click/Typer boilerplate, obvious pip/venv commands, pyproject.toml syntax

When to Read Support Files

• Starting a new CLI? Read references/project-structure-patterns.md for the recommended layout
• Choosing Click vs Typer? Read examples/click-cli-pattern.md and examples/typer-cli-pattern.md to compare
• Setting up pyproject.toml? Read examples/pyproject-layout.md for a complete working config
• Writing tests? Read references/testing-and-validation.md for CliRunner patterns and exit code testing
• Preparing to publish? Read references/packaging-and-release.md for the build→check→upload workflow