Toolbelt CLI

Scaffold projects, draft Conventional Commits, and audit repositories.

Table of Contents

• Overview
• Installation
• Command Reference
• Usage
• Feature Tour & Usage Examples
  • 1. Project Scaffolding (toolbelt new)
  • 2. AI-Powered Commits (toolbelt commit)
  • 3. Repository Auditing (toolbelt audit)
  • 4. Version Check (toolbelt version)
• Configuration & Environment Variables
• Architecture & Tech Stack
• Development & Testing
• Deployments
• Publishing to PyPI
• Contributing
• License

Overview

Toolbelt CLI is a Python 3.11+ command-line utility built with Typer, Rich, and Jinja2. It provides starter templates for Python, Node.js/TypeScript, and Java, commit-message drafting from staged Git changes, repository checks, and an optional PyPI update check.

Installation

With pipx (Recommended)

Isolate CLI tools in their own dedicated virtual environments:

pipx install toolbelt-cli

With uv

Fast single-step tool installation:

uv tool install toolbelt-cli

With standard pip

pip install toolbelt-cli

Install from source

git clone https://github.com/crnjihia/toolbelt-cli.git
cd toolbelt-cli
pip install -e ".[dev]"

The installation provides both toolbelt and zana command names.

Command Reference

Usage

toolbelt --help
toolbelt new python my_service
git add src/
toolbelt commit --dry-run
toolbelt audit .
toolbelt version

toolbelt commit reads staged changes. Use --dry-run to preview a message without creating a commit.

Feature Tour

1. toolbelt new <type> <name>

Scaffolds a new project directory. When options are omitted, the command prompts for author, license, CI, and Docker choices:

toolbelt new python my_service

Author name [Jane Doe]: Jane Doe
License (MIT | Apache-2.0 | none) [MIT]: MIT
Include CI? (y/n) [True]: y
Include Docker? (y/n) [False]: y

┌──────────────────────────── 🎉 Toolbelt Scaffold ────────────────────────────┐
│ ✨ Project successfully scaffolded!                                         │
│                                                                             │
│ Next steps:                                                                 │
│ cd my_service && make install && make test                                  │
└─────────────────────────────────────────────────────────────────────────────┘

Supported Stacks & Project Layouts

• Python (toolbelt new python <name>):

  • src/<name>/__init__.py, main.py
  • tests/test_main.py
  • pyproject.toml (configured with Ruff, MyPy, and Pytest)
  • .pre-commit-config.yaml
  • Makefile (install, test, lint, format, clean)
  • README.md, .gitignore, and optionally LICENSE
  • .github/workflows/ci.yml when CI is enabled
  • Dockerfile when Docker is enabled

• Node.js / TypeScript (toolbelt new node <name>):

  • package.json (TypeScript, ESLint, Prettier, and Vitest dependencies/scripts)
  • tsconfig.json
  • src/index.ts, src/index.test.ts
  • .eslintrc.json, .prettierrc
  • README.md, .gitignore, and optionally LICENSE

• Java (toolbelt new java <name>):

  • pom.xml (Maven, JUnit 5 Jupiter, compiler plugins)
  • src/main/java/com/<name>/App.java
  • src/test/java/com/<name>/AppTest.java
  • README.md, .gitignore, and optionally LICENSE

--yes accepts defaults: the configured Git author (or Developer), MIT license, CI enabled, and Docker disabled. CI and Docker templates are currently available for Python projects.

2. toolbelt commit

Reads your staged git diff (git diff --staged) and drafts a Conventional Commit message:

git add src/
toolbelt commit

┌────────────────────────── Proposed Commit Message ──────────────────────────┐
│ feat(auth): add bearer token validator and refresh middleware              │
└─────────────────────────────────────────────────────────────────────────────┘
Apply commit? [y/n/edit] (y): y
✅ Commit created successfully!

• Claude integration: Set ANTHROPIC_API_KEY to draft a message with the Anthropic API (claude-sonnet-4). The staged diff is sent to Anthropic when this is enabled.
• Local fallback: Without an API key, a heuristic uses the diff to draft a message without making a network call.
• Dry-run Mode: Preview generated messages without applying commits using toolbelt commit --dry-run.
• Confirmation: Review, edit, or reject the proposed message before committing. --yes skips confirmation.

Use --type and --scope to provide parts of the commit header:

toolbelt commit --type feat --scope cli

3. toolbelt audit [path]

Performs a structured quality check on any repository:

toolbelt audit .

• Auto-Fix (--fix): Prompts to create a missing .gitignore and/or MIT or Apache-2.0 LICENSE. It does not repair other failed checks.
• JSON Mode (--json): Outputs machine-readable JSON for integration into reporting tools or CI/CD pipelines.
• Exit status: Returns 0 when all checks pass and 1 when one or more checks fail.

4. toolbelt version

Displays installed package version and checks whether updates are available on PyPI:

toolbelt version

Configuration & Environment Variables

The optional ANTHROPIC_API_KEY environment variable is used by toolbelt commit. The CLI does not load .env files; set the variable in your shell before running the command.

PowerShell:

$env:ANTHROPIC_API_KEY = "your-api-key"
toolbelt commit

macOS/Linux:

export ANTHROPIC_API_KEY="your-api-key"
toolbelt commit

Without this variable, commit-message generation uses the local fallback.

Architecture & Tech Stack

toolbelt-cli/
├── src/toolbelt/
│   ├── cli.py             # Typer application definition and routing
│   ├── commands/          # Subcommand handlers (new, commit, audit, version)
│   ├── services/          # Scaffolder, LLM Commit Generator, and Auditor
│   ├── templates/         # Jinja2 project templates (python, node, java)
│   └── utils/             # Git interface, Rich console helpers
├── tests/                 # Full offline pytest test suite with CliRunner
└── .github/workflows/     # CI matrix & PyPI Trusted Publishing release

• CLI Framework: Typer
• Terminal UI: Rich
• Templating: Jinja2
• HTTP Client: HTTPX
• LLM Integration: Anthropic Python SDK
• Quality: Ruff & MyPy
• Testing: Pytest & CliRunner

Development & Testing

Run the automated test suite locally:

# Run unit and integration tests (100% offline)
pytest -v

# Check linting and style
ruff check .
ruff format --check .

# Run static type analysis
mypy src

Deployments

GitHub Actions manages CI, the documentation site, and PyPI releases:

• CI (.github/workflows/ci.yml) runs on pushes and pull requests targeting main. It tests Python 3.11 and 3.12 with Ruff, MyPy, and Pytest.
• Documentation (.github/workflows/pages.yml) deploys the static docs/ site to GitHub Pages when documentation or its workflow changes on main; it can also be started manually. In repository settings, Pages must use GitHub Actions as its deployment source.
• PyPI release (.github/workflows/release.yml) runs for tags matching v*. It builds and checks the package, then publishes using PyPI Trusted Publishing (OIDC).

Configure PyPI Trusted Publishing

Before the first release, register a publisher on PyPI for the toolbelt-cli project with these exact values:

The GitHub repository must also have a pypi environment. The build and distribution checks can pass even when publishing is not configured; in that case, the publish step fails with an invalid-publisher error. Configure the publisher in the PyPI project settings. Do not add a PyPI API token to the workflow for this OIDC setup.

For a release, update the version in pyproject.toml and src/toolbelt/__init__.py, update CHANGELOG.md, then push a version tag:

git tag v0.3.0
git push origin v0.3.0

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository on GitHub.
2. Create a feature branch: git checkout -b feat/my-new-feature
3. Ensure tests, lint, formatting, and type checks pass: pytest -v, ruff check ., ruff format --check ., and mypy src.
4. Commit your changes using conventional commits: git commit -m "feat(scope): describe change"
5. Open a Pull Request.

License

Distributed under the MIT License.