Installation

Install HelixCommit on your system

Requirements

Python 3.9+

Required runtime environment

Git

Must be installed and in PATH

pip

Python package manager

Verify your Python version:

python --version

HelixCommit works on macOS, Linux, and Windows. Git must be installed and accessible in your system PATH.

---

Install via pip

The simplest way to install HelixCommit is using pip from PyPI.

pip install helixcommit

After installation, verify that HelixCommit is available by running helixcommit --help

---

Using a virtual environment

You should install HelixCommit in a virtual environment to avoid conflicts with other Python packages.

venv

# Create a virtual environment
python -m venv .venv

# Activate the virtual environment
source .venv/bin/activate  # On macOS/Linux
# or
.venv\Scripts\activate  # On Windows

# Install HelixCommit
pip install helixcommit

conda

# Create a conda environment
conda create -n helixcommit python=3.11

# Activate the environment
conda activate helixcommit

# Install HelixCommit
pip install helixcommit

pipx

# Install with pipx for isolated CLI tool
pipx install helixcommit

# Verify installation
helixcommit --version

Using pipx is ideal for installing HelixCommit as a standalone CLI tool without managing virtual environments.

---

Install from source

You can install the latest development version directly from GitHub.

Clone and install

# Clone the repository
git clone https://github.com/bjornefisk/helixcommit.git
cd helixcommit

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in editable mode
pip install -e .

Installing in editable mode with -e allows you to modify the source code and see changes immediately without reinstalling.

Install development dependencies

If you plan to contribute or run tests, install the development dependencies:

pip install -e ".[dev]"

This installs additional packages for testing, linting, and type checking:

Package	Purpose
pytest	Running tests
ruff	Code formatting and linting
mypy	Static type checking
pytest-cov	Coverage reports

---

Verify installation

After installing HelixCommit, verify that it works correctly.

1. Check the version

   Run the following command to display the installed version:

   helixcommit --version
   

   Expected output will show the installed HelixCommit version, for example:

   helixcommit, version 1.1.0
   
2. Display help information

   Verify all commands are available:

   helixcommit --help
   

   You should see a list of available commands and options.

3. Generate your first release notes

   Navigate to any Git repository and run:

   helixcommit generate --unreleased --no-prs --format markdown
   

   If you see release notes output, HelixCommit is installed correctly and ready to use!

---

Optional dependencies

HelixCommit includes optional features that require additional dependencies.

GitHub integration

GitHub integration is included by default through the PyGithub package. To use it, you need a GitHub personal access token:

export GITHUB_TOKEN=your_github_token_here

Create a GitHub token at github.com/settings/tokens with repo scope for private repositories or no special permissions for public repositories.

AI summarization

AI features require API keys from supported providers:

OpenAI

export OPENAI_API_KEY=sk-...

helixcommit generate --unreleased --use-llm --openai-model gpt-4o-mini

Get your API key from platform.openai.com/api-keys

OpenRouter

export OPENROUTER_API_KEY=sk-or-...

helixcommit generate --unreleased --use-llm --llm-provider openrouter

Get your API key from openrouter.ai

OpenRouter provides access to multiple AI models, including free options like meta-llama/llama-3.3-70b-instruct:free

ChromaDB for advanced RAG

For advanced retrieval-augmented generation (RAG) features, install ChromaDB:

pip install chromadb

Then use the chroma backend when generating summaries:

helixcommit generate --unreleased --use-llm --rag-backend chroma

---

Updating HelixCommit

Keep HelixCommit up to date to access the latest features and bug fixes.

Update from PyPI

pip install --upgrade helixcommit

Update from source

cd helixcommit
git pull origin main
pip install -e ".[dev]"

---

Uninstalling

To remove HelixCommit from your system:

pip uninstall helixcommit

---

Troubleshooting

Command not found after installation

If helixcommit is not found after installation, ensure that Python’s scripts directory is in your PATH.

# On macOS/Linux
export PATH="$HOME/.local/bin:$PATH"

# On Windows (PowerShell)
$env:Path += ";$HOME\AppData\Local\Programs\Python\Python3XX\Scripts"

Add this to your shell configuration file (.bashrc, .zshrc, etc.) to make it permanent.

Permission denied errors

If you encounter permission errors during installation:

# Install for current user only
pip install --user helixcommit

# Or use a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate
pip install helixcommit

SSL certificate errors

If you see SSL certificate errors when installing:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org helixcommit

Only use this workaround if absolutely necessary. It’s better to fix the underlying SSL certificate issue on your system.

Git not found

HelixCommit requires Git to be installed and accessible. Install Git for your operating system:

Platform	Command
macOS	brew install git
Debian/Ubuntu	sudo apt install git
RHEL/CentOS	sudo yum install git
Windows	Download from git-scm.com

Verify Git is installed:

git --version

---

Next steps

Quick start guide

Generate your first release notes in minutes

CLI reference

Explore all available commands and options