Python CLI Template

This repository is a reusable template for bootstrapping Python CLI projects with typer, uv, and a src/ package layout.

What this template provides

• Project scaffolding and package naming via scripts/setup.sh
• Optional follow-up automation scripts for:
  • DVC initialization (scripts/setup_dvc.sh)
  • Minimal GitHub Actions CI workflow (scripts/setup_github_actions.sh)
• Cursor rules in .cursor/rules/ to enforce coding conventions

Project workflow

1) Generate a new project from this template

Run from the template root:

bash scripts/setup.sh

The script will:

• Ask for the new project/package name
• Ask for a destination parent path (default: same parent directory as this template)
• Copy the template into a new folder named after your project
• Rename the package under src/
• Update pyproject.toml placeholders
• Cache the generated project path in .cache/template-last-project
• Optionally run uv bootstrap (uv sync, uv venv, uv pip install -e .)

2) Run optional follow-up setup scripts

Both scripts can use either:

• The cached project path from .cache/template-last-project, or
• An explicit project path argument

DVC setup

bash scripts/setup_dvc.sh
# or
bash scripts/setup_dvc.sh /absolute/path/to/your-project

Behavior:

• Validates target path
• Initializes DVC only if it is not already initialized
• Does not configure remotes automatically

GitHub Actions setup

bash scripts/setup_github_actions.sh
# or
bash scripts/setup_github_actions.sh /absolute/path/to/your-project

To replace existing workflows safely:

bash scripts/setup_github_actions.sh --reset-workflows

Behavior:

• Validates target path
• Writes a minimal CI workflow at .github/workflows/ci.yml
• With --reset-workflows, moves existing workflows to a timestamped backup folder first

Template conventions

• CLI-first development with typer
• Code lives under src/${package_name}/
• Pipeline modules follow:
  • abc.ABC + @abstractmethod
  • Strategy Pattern
  • Factory Method
• Fail-fast error handling by default
• Central paths/constants in src/${package_name}/config.py using pathlib.Path
• Readability over cleverness

See .cursor/rules/ for detailed guidance applied in Cursor.

Notes

• .cache/template-last-project is local state and should not be committed.
• If your target project already exists, scripts/setup.sh will exit without overwriting it.