py-cli-boilerplate

A minimal Python CLI boilerplate template for GitHub-hosted projects.

Usage as Template

1. Copy the contents of this repository
2. Find and replace pycliboilerplate with your desired program name
3. Rename src/pycliboilerplate/ directory to match your program name
4. Update pyproject.toml with your project details
5. Update badge URLs in README.md with your repository information

Optional Setup

• Enable Dependabot: Go to Settings > Code security and analysis > Dependabot to enable automatic dependency updates
• Enable Codecov: Set up Codecov integration for code coverage tracking

Installation

Install the package:

pip install .

Install with dev dependencies (pytest, ruff):

pip install -e .[dev]

CLI Usage

$pycliboilerplate --help

Usage: pycliboilerplate [OPTIONS] FOOBAR

  FOOBAR is an example argument, it's value is printed to stdout

Options:
  -v, --verbose  Increase verbosity (-v for INFO, -vv for DEBUG)
  --save-log     Write log output to log.txt
  --version      Show the version and exit.
  --help         Show this message and exit.

Example:

$pycliboilerplate "hello world" -vv

2025-12-15 14:14:32 DEBUG    cli.py:22 (cli): Debug logging enabled
2025-12-15 14:14:32 INFO     cli.py:25 (cli): pycliboilerplate started
hello world
2025-12-15 14:14:32 INFO     cli.py:34 (cli): pycliboilerplate finished

Library Usage

Run from Python:

from pycliboilerplate import invoke
invoke(["-vv","hello world"])

Development

Run tests:

pytest tests/

Check code quality:

ruff check
ruff format --check

Install pre-commit hook (runs ruff automatically before commits):

cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

The CI workflow in .github/workflows/ci.yml automatically runs tests and code quality checks on every push.

Versioning

Version is derived from git tags using hatch-vcs with local_scheme = "no-local-version":

• Clean tagged commit: 1.0.0
• Commits after tag: 1.0.1.devN (where N is commit count after tag)
• No tag exists: 0.1.devN

Create a tag:

git tag v1.0.0

Publishing

This project includes a GitHub Actions workflow for publishing to PyPI. See the pypa/gh-action-pypi-publish documentation for configuration details.

Acknowledgements

This template uses:

• Click - For building CLI interfaces
• colorlog - For colored logging output

License

MIT