CLI reference

Quick reference

Command	Description
`helixcommit generate`	Generate release notes from Git history
`helixcommit generate-commit`	Generate commit messages using AI
`helixcommit preview`	Preview changelog in a beautifully formatted panel
`helixcommit browse`	Browse commits interactively with detailed views
`helixcommit search`	Search commits by keyword, author, or type
`helixcommit --version`	Display installed version
`helixcommit --help`	Show help information

helixcommit generate --unreleased --format markdown

helixcommit generate --since-tag v1.0.0 --until-tag v2.0.0 --out release.md

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

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

helixcommit generate --since "2024-01-01" --until HEAD --format html

Commands

generate

Generate release notes from Git commit history.

helixcommit generate [OPTIONS]

generate-commit

Generate a commit message from staged changes using AI.

helixcommit generate-commit [OPTIONS]

This command analyzes your staged changes (git diff --staged), generates a commit message using an AI model, and enters an interactive loop where you can review, refine, or commit the message.

Interactive commands:

c (commit): Commits the changes with the generated message
r (reply): Chat with the AI to refine the message
q (quit): Abort the operation

Options:

string

default:"openrouter"

The AI provider to use (openai or openrouter).

string

default:"meta-llama/llama-3.1-8b-instruct:free"

The OpenRouter model ID. Defaults to a free model.

string

default:"gpt-4o-mini"

The OpenAI model ID.

boolean

default:"false"

Skip the confirmation prompt (not recommended for interactive use).

boolean

default:"true"

Show or hide the staged diff preview before generating.

preview

Preview changelog in a beautifully formatted terminal panel.

helixcommit preview [OPTIONS]

Shows a live preview of what your changelog will look like without generating any files. Displays commits in a styled table and a formatted changelog panel. Options:

string

Preview commits after this tag.

string

Preview commits up to this tag.

boolean

default:"false"

Show HEAD vs latest tag.

integer

Limit the number of commits to preview.

boolean

default:"false"

Exclude merge commits from the preview.

browse

Browse commits interactively with detailed views.

helixcommit browse [OPTIONS]

Navigate through commits with keyboard controls, view details, and explore your commit history in a rich terminal interface.

Navigation commands:

n (next): Go to next commit
p (prev): Go to previous commit
d (diff): Show diff for current commit
q (quit): Exit browser

Options:

string

Browse commits after this tag.

string

Browse commits up to this tag.

boolean

default:"false"

Show HEAD vs latest tag.

integer

default:"50"

Maximum commits to load.

boolean

default:"false"

Exclude merge commits.

boolean

default:"false"

Show commit bodies in the detail view.

search

Search commits by keyword, author, or type.

helixcommit search <QUERY> [OPTIONS]

Quickly find commits matching your search criteria with highlighted results and detailed information. Arguments:

string

required

Search query (searches subject, author, body). Supports regex patterns.

Options:

string

Filter by author name or email (regex pattern).

string

Filter by commit type (feat, fix, docs, etc.).

string

Search commits after this tag.

string

Search commits up to this tag.

integer

default:"50"

Maximum results to show.

boolean

default:"false"

Enable case-sensitive search.

Global Options

string

Color theme for terminal output.Options: dark, light, auto

helixcommit --theme dark generate --unreleased
helixcommit --theme light preview

Use auto to automatically detect your terminal’s color scheme.

Repository & Range Options

path

default:"current directory"

Path to the Git repository to analyze.

helixcommit generate --repo /path/to/repo

string

Start generating notes from commits after this tag.

helixcommit generate --since-tag v1.2.0 --until-tag v1.2.1

Use with --until-tag to generate notes for a specific version range.

string

Generate notes up to and including this tag.

helixcommit generate --until-tag v2.0.0

string

Start from this Git ref, commit SHA, or date expression.

# Using commit SHA
helixcommit generate --since abc123def

# Using branch
helixcommit generate --since main --until feature-branch

# Using date (Git rev-spec supports many date expressions)
helixcommit generate --since "2024-01-01"

string

default:"HEAD"

Generate notes up to this Git ref or commit SHA.

helixcommit generate --since v1.0.0 --until develop

boolean

default:"false"

Generate notes for commits between the latest tag and HEAD.

helixcommit generate --unreleased

This is equivalent to using --since-tag <latest-tag> --until HEAD

string

Filter commits to only include those after this date. Supports ISO 8601 dates and relative expressions.

# Using ISO date
helixcommit generate --since-date 2024-01-15

# Using relative expression
helixcommit generate --since-date "2 weeks ago"

# Combine with other filters
helixcommit generate --since-date "1 month ago" --until-date yesterday

Supported formats:

ISO 8601: 2024-01-15, 2024-01-15T10:30:00
Relative: 2 weeks ago, 3 days ago, 1 month ago
Keywords: yesterday, today

Date filtering can be combined with ref-based filtering (--since, --until) for precise control over which commits to include.

string

Filter commits to only include those before this date. Supports the same date formats as --since-date.

# Using ISO date
helixcommit generate --until-date 2024-06-01

# Using relative expression
helixcommit generate --until-date yesterday

# Filter a specific date range
helixcommit generate --since-date 2024-01-01 --until-date 2024-06-30

When using both --since-date and --until-date, commits within the specified date range (exclusive of since, inclusive of until) are included.

Output Options

string

default:"markdown"

Output format for the generated release notes.Options: markdown, html, text, json, yaml

# Markdown output (default)
helixcommit generate --format markdown

# HTML output
helixcommit generate --format html

# Plain text output
helixcommit generate --format text

# JSON output (for programmatic use)
helixcommit generate --format json

# YAML output (for CI/CD pipelines)
helixcommit generate --format yaml

path

Write output to the specified file instead of stdout.

helixcommit generate --unreleased --out RELEASE_NOTES.md

The directory will be created automatically if it doesn’t exist.

Filtering Options

boolean

default:"true"

Show or hide commit scopes in the output.

# Hide scopes
helixcommit generate --no-include-scopes

# Show scopes (default)
helixcommit generate --include-scopes

With scopes:

### Features
- **api**: Add new endpoint for user authentication (abc123)
- **ui**: Implement dark mode toggle (def456)

Without scopes:

### Features
- Add new endpoint for user authentication (abc123)
- Implement dark mode toggle (def456)

boolean

default:"false"

Skip GitHub API lookups for pull request information.

helixcommit generate --no-prs

Use this flag when working offline or to speed up generation when PR metadata isn’t needed.

boolean

default:"false"

Exclude merge commits from the generated release notes.

helixcommit generate --no-merge-commits

Merge commits often duplicate information from their constituent commits, so excluding them can make release notes cleaner.

integer

Limit the number of commits to process.

helixcommit generate --max-items 100

Useful for testing or when you only want recent changes.

boolean

default:"false"

Exit with status code 1 when no commits are found.

helixcommit generate --unreleased --fail-on-empty

Useful in CI/CD pipelines to detect when there are no changes to release.

Advanced Filtering

string[]

Only include commits of the specified types. Accepts space-separated values.

# Only include features and fixes
helixcommit generate --unreleased --include-types feat fix

# Only include documentation changes
helixcommit generate --unreleased --include-types docs

Supported types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

For non-conventional commits, the type is inferred using heuristics based on commit message content.

string[]

Exclude commits with the specified scopes. Accepts space-separated values.

# Exclude dependency updates and CI changes
helixcommit generate --unreleased --exclude-scopes deps ci

# Exclude internal tooling changes
helixcommit generate --unreleased --exclude-scopes internal tooling

Commits without a scope are never excluded by this filter.

string

Filter commits by author name or email using a regex pattern.

# Only include commits from company email addresses
helixcommit generate --unreleased --author-filter "@mycompany\\.com$"

# Only include commits from a specific author
helixcommit generate --unreleased --author-filter "Alice"

# Exclude bot commits (use with caution - regex must match to include)
helixcommit generate --unreleased --author-filter "^(?!.*bot).*$"

The regex is matched case-insensitively against both the author name and email.

AI & LLM Options

boolean

default:"false"

Enable AI-powered summarization for release notes.

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

Requires OPENAI_API_KEY or OPENROUTER_API_KEY environment variable depending on the provider.

string

default:"openai"

AI provider to use for summarization.Options: openai, openrouter

# Use OpenAI
helixcommit generate --use-llm --llm-provider openai

# Use OpenRouter
helixcommit generate --use-llm --llm-provider openrouter

string

default:"gpt-4o-mini"

OpenAI model to use for summarization.

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

Model	Speed	Quality	Cost
`gpt-4o-mini`	Fast	Excellent	Low
`gpt-4o`	Moderate	Outstanding	High
`gpt-3.5-turbo`	Very fast	Good	Very low

string

OpenAI API key (can also be set via OPENAI_API_KEY environment variable).

helixcommit generate --use-llm --openai-api-key sk-...

Using the environment variable is more secure than passing the key as a command-line argument.

string

default:"meta-llama/llama-3.1-8b-instruct:free"

OpenRouter model to use for summarization.

helixcommit generate \
  --use-llm \
  --llm-provider openrouter \
  --openrouter-model x-ai/grok-4.1-fast:free

The default OpenRouter model is x-ai/grok-4.1-fast:free. See openrouter.ai/docs for the latest available models.

string

OpenRouter API key (can also be set via OPENROUTER_API_KEY environment variable).

helixcommit generate \
  --use-llm \
  --llm-provider openrouter \
  --openrouter-api-key sk-or-...

string

Domain scope for the AI system prompt to constrain tone and terminology.

helixcommit generate \
  --use-llm \
  --domain-scope "software release notes"

Examples: "software release notes", "conservation", "healthcare", "finance"

string

Add expert roles for multi-expert prompting (can be specified multiple times).

helixcommit generate \
  --use-llm \
  --expert-role "Product Manager" \
  --expert-role "Tech Lead" \
  --expert-role "QA Engineer"

Default roles: Product Manager, Tech Lead, QA Engineer

string

default:"simple"

RAG (Retrieval Augmented Generation) backend to use.Options: simple, chroma

# Simple keyword-based retrieval (default)
helixcommit generate --use-llm --rag-backend simple

# ChromaDB vector retrieval (requires chromadb package)
helixcommit generate --use-llm --rag-backend chroma

The chroma backend requires installing ChromaDB: pip install chromadb

path

Path to cache file for AI-generated summaries.

helixcommit generate \
  --use-llm \
  --summary-cache .cache/summaries.json

Default: .helixcommit-cache/summaries.json

Caching reduces API costs by reusing previously generated summaries for unchanged commits.

Git Platform Options

GitHub

string

GitHub personal access token for API requests.

helixcommit generate --github-token ghp_...

Set the GITHUB_TOKEN environment variable instead of passing it as an argument for better security.

Required permissions:

Public repositories: No special permissions needed
Private repositories: repo scope

Create a token at github.com/settings/tokens

GitLab

string

GitLab personal access token for API requests.

helixcommit generate --gitlab-token glpat-...

Set the GITLAB_TOKEN environment variable instead of passing it as an argument for better security.

Required permissions:

read_api scope for API access
read_repository scope for private projects

Create a token at gitlab.com/-/user_settings/personal_access_tokens

Bitbucket

string

Bitbucket App Password for API requests.

helixcommit generate --bitbucket-token ...

Set the BITBUCKET_TOKEN environment variable instead of passing it as an argument for better security.

Required permissions:

Repositories: Read
Pull requests: Read

Create an App Password at bitbucket.org/account/settings/app-passwords

Environment Variables

string

GitHub personal access token for API authentication.

export GITHUB_TOKEN=ghp_...
helixcommit generate --unreleased

Improves rate limits and enables access to private repositories.

string

OpenAI API key for AI summarization.

export OPENAI_API_KEY=sk-...
helixcommit generate --use-llm

Required when using --use-llm with the OpenAI provider.

string

OpenRouter API key for AI summarization.

export OPENROUTER_API_KEY=sk-or-...
helixcommit generate --use-llm --llm-provider openrouter

Required when using --use-llm --llm-provider openrouter.

string

GitLab personal access token for API authentication.

export GITLAB_TOKEN=glpat-...
helixcommit generate --unreleased

Enables access to private GitLab projects and improves rate limits.

string

Bitbucket App Password for API authentication.

export BITBUCKET_TOKEN=...
helixcommit generate --unreleased

Enables access to private Bitbucket repositories and improves rate limits.

GitHub Client Configuration

Variable	Default	Description
`HELIXCOMMIT_GH_MAX_RETRIES`	`3`	Maximum number of GitHub API retry attempts
`HELIXCOMMIT_GH_BACKOFF_BASE_SEC`	`0.5`	Base delay in seconds for exponential backoff
`HELIXCOMMIT_GH_BACKOFF_CAP_SEC`	`8`	Maximum backoff delay in seconds
`HELIXCOMMIT_GH_CACHE`	`false`	Enable on-disk caching for GitHub API responses
`HELIXCOMMIT_GH_CACHE_DIR`	`.helixcommit-cache/github`	Directory for GitHub API cache files
`HELIXCOMMIT_GH_CACHE_TTL_MINUTES`	`10`	Cache time-to-live in minutes

Common Usage Patterns

Generate notes for CI/CD release

#!/bin/bash
# Generate release notes in CI pipeline

export GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}

helixcommit generate \
  --since-tag $PREVIOUS_TAG \
  --until-tag $CURRENT_TAG \
  --format markdown \
  --out RELEASE_NOTES.md \
  --fail-on-empty

Preview unreleased changes with AI

export OPENAI_API_KEY=sk-...

helixcommit generate \
  --unreleased \
  --use-llm \
  --openai-model gpt-4o-mini \
  --format markdown \
  --out preview.md

Generate HTML changelog for website

helixcommit generate \
  --since-tag v1.0.0 \
  --until-tag v2.0.0 \
  --format html \
  --out public/changelog.html \
  --no-merge-commits

Quick offline generation

# Fast generation without external API calls
helixcommit generate \
  --unreleased \
  --no-prs \
  --format text

Exit Codes

Code	Meaning
`0`	Success - release notes generated successfully
`1`	Error - no commits found (when `--fail-on-empty` is used), or other error occurred
`2`	Usage error - invalid arguments or options

Getting help

Display help information for the CLI:

# Show general help
helixcommit --help

# Show help for generate command
helixcommit generate --help

Next steps

Configuration guide

Learn about configuration options and customization

AI features

Explore AI-powered summarization capabilities

Examples

See real-world usage examples and patterns

Python API

Use HelixCommit programmatically in Python

Get Started

Core

Advanced

Examples

Community

Quick reference

Commands

generate

generate-commit

preview

browse

search

Global Options

Repository & Range Options

Output Options

Filtering Options

Advanced Filtering

AI & LLM Options

Git Platform Options

GitHub

GitLab

Bitbucket

Environment Variables

GitHub Client Configuration

Common Usage Patterns

Exit Codes

Getting help

Next steps

Configuration guide

AI features

Examples

Python API

​Quick reference

​Commands

​generate

​generate-commit

​preview

​browse

​search

​Global Options

​Repository & Range Options

​Output Options

​Filtering Options

​Advanced Filtering

​AI & LLM Options

​Git Platform Options

​GitHub

​GitLab

​Bitbucket

​Environment Variables

​GitHub Client Configuration

​Common Usage Patterns

​Exit Codes

​Getting help

​Next steps

Configuration guide

AI features

Examples

Python API

Quick reference

Commands

generate

generate-commit

preview

browse

search

Global Options

Repository & Range Options

Output Options

Filtering Options

Advanced Filtering

AI & LLM Options

Git Platform Options

GitHub

GitLab

Bitbucket

Environment Variables

GitHub Client Configuration

Common Usage Patterns

Exit Codes

Getting help

Next steps