Python CLI Template

A template for creating Python CLI tools that publish to PyPI and ClawHub.

Using This Template

1. Create a new repo from this template (or copy the files)
2. Find and replace these placeholders:
   • my_tool → your package name (snake_case, e.g., flight_search)
   • my-tool → your PyPI name (kebab-case, e.g., flight-search)
   • My Tool → your display name (e.g., Flight Search)
   • A brief description → your description
3. Rename the directory: mv my_tool your_package_name
4. Update SKILL.md with your tool's details
5. Add your code in your_package_name/core.py and CLI in cli.py
6. Add PYPI_TOKEN to repo secrets (Settings → Secrets → Actions)

What's Included

File	Purpose
.github/workflows/ci.yml	Lint + test on PR, publish to PyPI on v* tags
AGENTS.md	AI contributor instructions (how to release, style guide)
SKILL.md	ClawHub skill definition for OpenClaw agents
CHANGELOG.md	Keep a Changelog format
install.sh	curl installer (auto-detects uv/pipx/pip)
pyproject.toml	Modern Python packaging with uv
pytest.ini	Test configuration

Release Workflow

# 1. Bump version in pyproject.toml
# 2. Update CHANGELOG.md
# 3. Commit changes
git add -A && git commit -m "Bump version to X.Y.Z"

# 4. Tag and push
git tag vX.Y.Z
git push && git push --tags

# 5. CI auto-publishes to PyPI ✨

⚠️ Never manually publish to PyPI - always use git tags so GitHub releases stay in sync.

Installation (for users of your tool)

# Recommended: uv
uv tool install my-tool

# Or: pipx
pipx install my-tool

# Or: pip
pip install my-tool

# Or: one-liner
curl -fsSL https://raw.githubusercontent.com/Olafs-World/my-tool/main/install.sh | bash

ClawHub

clawhub install my-tool

License

MIT