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

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:

--llm-provider

string

default:"openrouter"

The AI provider to use (openai or openrouter).

--openrouter-model

string

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

The OpenRouter model ID. Defaults to a free model.

--openai-model

string

default:"gpt-4o-mini"

The OpenAI model ID.

--no-confirm

boolean

default:"false"

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

--show-diff / --no-show-diff

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:

--since-tag

string

Preview commits after this tag.

--until-tag

string

Preview commits up to this tag.

--unreleased

boolean

default:"false"

Show HEAD vs latest tag.

--max-items

integer

Limit the number of commits to preview.

--no-merge-commits

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:

--since-tag

string

Browse commits after this tag.

--until-tag

string

Browse commits up to this tag.

--unreleased

boolean

default:"false"

Show HEAD vs latest tag.

--max-items

integer

default:"50"

Maximum commits to load.

--no-merge-commits

boolean

default:"false"

Exclude merge commits.

--show-body

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:

QUERY

string

required

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

Options:

--author, -a

string

Filter by author name or email (regex pattern).

--type, -t

string

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

--since-tag

string

Search commits after this tag.

--until-tag

string

Search commits up to this tag.

--max-results

integer

default:"50"

Maximum results to show.

--case-sensitive

boolean

default:"false"

Enable case-sensitive search.

Global Options

--theme, -t

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

--repo

path

default:"current directory"

Path to the Git repository to analyze.

helixcommit generate --repo /path/to/repo

--since-tag

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.

--until-tag

string

Generate notes up to and including this tag.

helixcommit generate --until-tag v2.0.0

--since

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"

--until

string

default:"HEAD"

Generate notes up to this Git ref or commit SHA.

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

--unreleased

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

--since-date

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.

--until-date

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

--format

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

--out

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

--include-scopes

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)

--no-prs

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.

--no-merge-commits

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.

--max-items

integer

Limit the number of commits to process.

helixcommit generate --max-items 100

Useful for testing or when you only want recent changes.

--fail-on-empty

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

--include-types

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.

--exclude-scopes

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.

--author-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

--use-llm

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.

--llm-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

--openai-model

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

--openai-api-key

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.

--openrouter-model

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.

--openrouter-api-key

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-...

--domain-scope

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"

--expert-role

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

--rag-backend

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

--summary-cache

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

--github-token

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

--gitlab-token

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

--bitbucket-token

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

GITHUB_TOKEN

string

GitHub personal access token for API authentication.

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

Improves rate limits and enables access to private repositories.

OPENAI_API_KEY

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.

OPENROUTER_API_KEY

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.

GITLAB_TOKEN

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.

BITBUCKET_TOKEN

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

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