py-cli-boilerplate

An opinionated Python CLI boilerplate template for GitHub-hosted projects.

Usage as Template

1. Create a repository directly using this template
2. Replace py-cli-boilerplate with your distribution name in all files
3. Replace py_cli_boilerplate with your package name in all files (dashes not allowed in package names)
4. Rename src/py_cli_boilerplate/ directory to your package name
5. Update pyproject.toml with your project details
6. Update badge URLs in README.md with your repository URL

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
• Publishing on PyPI: See Publishing
• Typed Project: This template is configured as a typed project with the py.typed marker and Typing :: Typed classifier in pyproject.toml. If your project won't provide type hints, remove src/py_cli_boilerplate/py.typed and the typing classifier from pyproject.toml

Installation (End Users)

Using uv (preferred method)

uv automatically handles Python installation and setup in the background so you don't have to.

If your package is available on PyPI, the user can simply run the program using uvx:

uvx py-cli-boilerplate

Using pip

Make sure Python v3.10 or higher is installed.

Create a virtual environment (optional):

python -m venv .venv
source .venv/bin/activate

Install the package:

pip install py-cli-boilerplate

Or, if the package is not (yet) available on PyPI, clone the repo and:

pip install .

CLI Usage

$py-cli-boilerplate --help

Usage: py-cli-boilerplate [OPTIONS] FOOBAR

  FOOBAR is an example argument, its 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:

$py-cli-boilerplate "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): Program started
hello world
2025-12-15 14:14:32 INFO     cli.py:34 (cli): Program finished

Library Usage

Run from Python:

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

Development

Installation

Install uv. Then, install dependencies & activate the automatically generated virtual environment:

uv sync --locked
source .venv/bin/activate

Skip --locked to use the newest dependencies (this might modify uv.lock)

Testing

Run tests:

pytest

Quality Assurance (QA)

Check code quality:

ruff check
ruff format --check
ty check

Better yet, install the pre-commit hook, which runs code quality checks before every commit:

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

The CI build workflow (.github/workflows/build.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 via a GitHub release (see Publishing) or manually using git tag.

Publishing

This project includes a GitHub Actions workflow (pypi-publish.yml) that uses pypa/gh-action-pypi-publish for publishing to test.pypi.org (the Test Python Package Index).

To publish:

1. Create an account on test.pypi.org.
2. Add the project to the list of trusted publishers.
3. Create a release on GitHub. This triggers the workflow.

To publish on pypi.org instead of test.pypi.org, remove the repository-url line from pypi-publish.yml and remove pypiBaseUrl from the PyPI badge url in README.md.

Acknowledgements

This template uses:

• Click - For building CLI interfaces

License

MIT