Skip to content

project rulesWorkflowpython

Python CLI Rules

Project rules for Python command line tools: argparse or Typer, clear exit codes, pyproject packaging, stderr logging and pytest.

npx workspacetemplates add python-cli-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file19 lines · 1.2 KBFile
# Project rules: Python CLI

## Layout and packaging
- Use a `src/<package>` layout and `pyproject.toml` with a `[project.scripts]` entry point. Keep `cli.py` thin; put logic in importable modules that take plain arguments.
- Pin the supported Python range and type-hint public functions. Run `mypy` or `pyright` in strict mode.

## Arguments and I/O
- Parse with `argparse` or Typer, never `sys.argv` by hand. Every option has help text; offer `--version` and `--help`.
- Write results to stdout and diagnostics to stderr. Offer `--json` for machine output. Read stdin when a path is `-`.
- Honor `NO_COLOR`; do not prompt when stdin is not a TTY.

## Errors and exit codes
- Return `0` on success, `1` for runtime failures, `2` for usage errors. Define a small exception hierarchy, catch it once in `main()` and print one clear line; show tracebacks only with `--debug`.
- Use `logging` configured from `-v` flags, not `print`, for diagnostics.

## Quality
- Make `main(argv=None) -> int` and call `sys.exit(main())` only under `__main__`.
- Test with pytest, `capsys` and `tmp_path`; assert exit codes and stderr text.
- Run `ruff check`, `ruff format --check` and `pytest` before finishing.

What it does

These rules turn a Python script into a command line tool people can install and trust. They define how arguments are parsed, where output goes and which exit codes mean what.

They suit tools that run in shells and CI pipelines, where predictable streams and codes matter more than clever features.

Example

you › Add a --format option that can output csv

agent › The agent adds a validated choice option, a csv writer module with no CLI imports, and a pytest case that checks stdout and exit code 2 on a bad value.

Questions

Argparse or Typer?
Either. Use argparse for zero dependencies and Typer when you want type-driven options; do not mix both.
Why a main that returns an int?
Tests can call it directly and check the code without spawning a subprocess.
  • Go CLI Rules

    Project rulesgo

    Free
  • Rust CLI Rules

    Project rulesrust

    Free
  • Bug Report Triage

    SkillWorkflow

    Free
  • Codebase Onboarding

    SkillWorkflow

    Free