> ## Documentation Index
> Fetch the complete documentation index at: https://lunr-f6858e75.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Complete reference for HelixCommit command-line interface

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

<CodeGroup>
  ```bash Basic usage theme={}
  helixcommit generate --unreleased --format markdown
  ```

  ```bash Between tags theme={}
  helixcommit generate --since-tag v1.0.0 --until-tag v2.0.0 --out release.md
  ```

  ```bash With AI summaries theme={}
  helixcommit generate --unreleased --use-llm --openai-model gpt-4o-mini
  ```

  ```bash Stream AI summaries (opt-in) theme={}
  helixcommit generate --unreleased --use-llm --stream-llm --openai-model gpt-4o-mini
  ```

  <ParamField query="--stream-llm" type="boolean" default="false">
    Stream AI-generated summaries character-by-character in the terminal (opt-in).
  </ParamField>

  ```bash Custom range theme={}
  helixcommit generate --since "2024-01-01" --until HEAD --format html
  ```
</CodeGroup>

***

## Commands

### generate

Generate release notes from Git commit history.

```bash theme={}
helixcommit generate [OPTIONS]
```

### generate-commit

Generate a commit message from staged changes using AI.

```bash theme={}
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.

<Info>
  **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
</Info>

**Options:**

<ParamField query="--llm-provider" type="string" default="openrouter">
  The AI provider to use (`openai` or `openrouter`).
</ParamField>

<ParamField query="--openrouter-model" type="string" default="meta-llama/llama-3.1-8b-instruct:free">
  The OpenRouter model ID. Defaults to a free model.
</ParamField>

<ParamField query="--openai-model" type="string" default="gpt-4o-mini">
  The OpenAI model ID.
</ParamField>

<ParamField query="--no-confirm" type="boolean" default="false">
  Skip the confirmation prompt (not recommended for interactive use).
</ParamField>

<ParamField query="--show-diff / --no-show-diff" type="boolean" default="true">
  Show or hide the staged diff preview before generating.
</ParamField>

### preview

Preview changelog in a beautifully formatted terminal panel.

```bash theme={}
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:**

<ParamField query="--since-tag" type="string">
  Preview commits after this tag.
</ParamField>

<ParamField query="--until-tag" type="string">
  Preview commits up to this tag.
</ParamField>

<ParamField query="--unreleased" type="boolean" default="false">
  Show HEAD vs latest tag.
</ParamField>

<ParamField query="--max-items" type="integer">
  Limit the number of commits to preview.
</ParamField>

<ParamField query="--no-merge-commits" type="boolean" default="false">
  Exclude merge commits from the preview.
</ParamField>

### browse

Browse commits interactively with detailed views.

```bash theme={}
helixcommit browse [OPTIONS]
```

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

<Info>
  **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
</Info>

**Options:**

<ParamField query="--since-tag" type="string">
  Browse commits after this tag.
</ParamField>

<ParamField query="--until-tag" type="string">
  Browse commits up to this tag.
</ParamField>

<ParamField query="--unreleased" type="boolean" default="false">
  Show HEAD vs latest tag.
</ParamField>

<ParamField query="--max-items" type="integer" default="50">
  Maximum commits to load.
</ParamField>

<ParamField query="--no-merge-commits" type="boolean" default="false">
  Exclude merge commits.
</ParamField>

<ParamField query="--show-body" type="boolean" default="false">
  Show commit bodies in the detail view.
</ParamField>

### search

Search commits by keyword, author, or type.

```bash theme={}
helixcommit search <QUERY> [OPTIONS]
```

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

**Arguments:**

<ParamField query="QUERY" type="string" required>
  Search query (searches subject, author, body). Supports regex patterns.
</ParamField>

**Options:**

<ParamField query="--author, -a" type="string">
  Filter by author name or email (regex pattern).
</ParamField>

<ParamField query="--type, -t" type="string">
  Filter by commit type (feat, fix, docs, etc.).
</ParamField>

<ParamField query="--since-tag" type="string">
  Search commits after this tag.
</ParamField>

<ParamField query="--until-tag" type="string">
  Search commits up to this tag.
</ParamField>

<ParamField query="--max-results" type="integer" default="50">
  Maximum results to show.
</ParamField>

<ParamField query="--case-sensitive" type="boolean" default="false">
  Enable case-sensitive search.
</ParamField>

***

## Global Options

<ParamField query="--theme, -t" type="string">
  Color theme for terminal output.

  **Options:** `dark`, `light`, `auto`

  ```bash theme={}
  helixcommit --theme dark generate --unreleased
  helixcommit --theme light preview
  ```

  <Tip>
    Use `auto` to automatically detect your terminal's color scheme.
  </Tip>
</ParamField>

***

## Repository & Range Options

<ParamField query="--repo" type="path" default="current directory">
  Path to the Git repository to analyze.

  ```bash theme={}
  helixcommit generate --repo /path/to/repo
  ```
</ParamField>

<ParamField query="--since-tag" type="string">
  Start generating notes from commits after this tag.

  ```bash theme={}
  helixcommit generate --since-tag v1.2.0 --until-tag v1.2.1
  ```

  <Tip>
    Use with `--until-tag` to generate notes for a specific version range.
  </Tip>
</ParamField>

<ParamField query="--until-tag" type="string">
  Generate notes up to and including this tag.

  ```bash theme={}
  helixcommit generate --until-tag v2.0.0
  ```
</ParamField>

<ParamField query="--since" type="string">
  Start from this Git ref, commit SHA, or date expression.

  ```bash theme={}
  # 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"
  ```
</ParamField>

<ParamField query="--until" type="string" default="HEAD">
  Generate notes up to this Git ref or commit SHA.

  ```bash theme={}
  helixcommit generate --since v1.0.0 --until develop
  ```
</ParamField>

<ParamField query="--unreleased" type="boolean" default="false">
  Generate notes for commits between the latest tag and HEAD.

  ```bash theme={}
  helixcommit generate --unreleased
  ```

  <Info>
    This is equivalent to using `--since-tag <latest-tag> --until HEAD`
  </Info>
</ParamField>

<ParamField query="--since-date" type="string">
  Filter commits to only include those after this date. Supports ISO 8601 dates and relative expressions.

  ```bash theme={}
  # 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`

  <Tip>
    Date filtering can be combined with ref-based filtering (`--since`, `--until`) for precise control over which commits to include.
  </Tip>
</ParamField>

<ParamField query="--until-date" type="string">
  Filter commits to only include those before this date. Supports the same date formats as `--since-date`.

  ```bash theme={}
  # 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
  ```

  <Info>
    When using both `--since-date` and `--until-date`, commits within the specified date range (exclusive of since, inclusive of until) are included.
  </Info>
</ParamField>

***

## Output Options

<ParamField query="--format" type="string" default="markdown">
  Output format for the generated release notes.

  **Options:** `markdown`, `html`, `text`, `json`, `yaml`

  ```bash theme={}
  # 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
  ```
</ParamField>

<ParamField query="--out" type="path">
  Write output to the specified file instead of stdout.

  ```bash theme={}
  helixcommit generate --unreleased --out RELEASE_NOTES.md
  ```

  <Check>
    The directory will be created automatically if it doesn't exist.
  </Check>
</ParamField>

***

## Filtering Options

<ParamField query="--include-scopes" type="boolean" default="true">
  Show or hide commit scopes in the output.

  ```bash theme={}
  # 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)
  ```
</ParamField>

<ParamField query="--no-prs" type="boolean" default="false">
  Skip GitHub API lookups for pull request information.

  ```bash theme={}
  helixcommit generate --no-prs
  ```

  <Tip>
    Use this flag when working offline or to speed up generation when PR metadata isn't needed.
  </Tip>
</ParamField>

<ParamField query="--no-merge-commits" type="boolean" default="false">
  Exclude merge commits from the generated release notes.

  ```bash theme={}
  helixcommit generate --no-merge-commits
  ```

  <Info>
    Merge commits often duplicate information from their constituent commits, so excluding them can make release notes cleaner.
  </Info>
</ParamField>

<ParamField query="--max-items" type="integer">
  Limit the number of commits to process.

  ```bash theme={}
  helixcommit generate --max-items 100
  ```

  Useful for testing or when you only want recent changes.
</ParamField>

<ParamField query="--fail-on-empty" type="boolean" default="false">
  Exit with status code 1 when no commits are found.

  ```bash theme={}
  helixcommit generate --unreleased --fail-on-empty
  ```

  <Info>
    Useful in CI/CD pipelines to detect when there are no changes to release.
  </Info>
</ParamField>

***

## Advanced Filtering

<ParamField query="--include-types" type="string[]">
  Only include commits of the specified types. Accepts space-separated values.

  ```bash theme={}
  # 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`

  <Info>
    For non-conventional commits, the type is inferred using heuristics based on commit message content.
  </Info>
</ParamField>

<ParamField query="--exclude-scopes" type="string[]">
  Exclude commits with the specified scopes. Accepts space-separated values.

  ```bash theme={}
  # Exclude dependency updates and CI changes
  helixcommit generate --unreleased --exclude-scopes deps ci

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

  <Tip>
    Commits without a scope are never excluded by this filter.
  </Tip>
</ParamField>

<ParamField query="--author-filter" type="string">
  Filter commits by author name or email using a regex pattern.

  ```bash theme={}
  # 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).*$"
  ```

  <Info>
    The regex is matched case-insensitively against both the author name and email.
  </Info>
</ParamField>

***

## AI & LLM Options

<ParamField query="--use-llm" type="boolean" default="false">
  Enable AI-powered summarization for release notes.

  ```bash theme={}
  helixcommit generate --use-llm --openai-model gpt-4o-mini
  ```

  <Warning>
    Requires `OPENAI_API_KEY` or `OPENROUTER_API_KEY` environment variable depending on the provider.
  </Warning>
</ParamField>

<ParamField query="--llm-provider" type="string" default="openai">
  AI provider to use for summarization.

  **Options:** `openai`, `openrouter`

  ```bash theme={}
  # Use OpenAI
  helixcommit generate --use-llm --llm-provider openai

  # Use OpenRouter
  helixcommit generate --use-llm --llm-provider openrouter
  ```
</ParamField>

<ParamField query="--openai-model" type="string" default="gpt-4o-mini">
  OpenAI model to use for summarization.

  ```bash theme={}
  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 |
</ParamField>

<ParamField query="--openai-api-key" type="string">
  OpenAI API key (can also be set via `OPENAI_API_KEY` environment variable).

  ```bash theme={}
  helixcommit generate --use-llm --openai-api-key sk-...
  ```

  <Tip>
    Using the environment variable is more secure than passing the key as a command-line argument.
  </Tip>
</ParamField>

<ParamField query="--openrouter-model" type="string" default="meta-llama/llama-3.1-8b-instruct:free">
  OpenRouter model to use for summarization.

  ```bash theme={}
  helixcommit generate \
    --use-llm \
    --llm-provider openrouter \
    --openrouter-model x-ai/grok-4.1-fast:free
  ```

  <Info>
    The default OpenRouter model is `x-ai/grok-4.1-fast:free`. See [openrouter.ai/docs](https://openrouter.ai/docs) for the latest available models.
  </Info>
</ParamField>

<ParamField query="--openrouter-api-key" type="string">
  OpenRouter API key (can also be set via `OPENROUTER_API_KEY` environment variable).

  ```bash theme={}
  helixcommit generate \
    --use-llm \
    --llm-provider openrouter \
    --openrouter-api-key sk-or-...
  ```
</ParamField>

<ParamField query="--domain-scope" type="string">
  Domain scope for the AI system prompt to constrain tone and terminology.

  ```bash theme={}
  helixcommit generate \
    --use-llm \
    --domain-scope "software release notes"
  ```

  Examples: `"software release notes"`, `"conservation"`, `"healthcare"`, `"finance"`
</ParamField>

<ParamField query="--expert-role" type="string" repeatable>
  Add expert roles for multi-expert prompting (can be specified multiple times).

  ```bash theme={}
  helixcommit generate \
    --use-llm \
    --expert-role "Product Manager" \
    --expert-role "Tech Lead" \
    --expert-role "QA Engineer"
  ```

  **Default roles:** Product Manager, Tech Lead, QA Engineer
</ParamField>

<ParamField query="--rag-backend" type="string" default="simple">
  RAG (Retrieval Augmented Generation) backend to use.

  **Options:** `simple`, `chroma`

  ```bash theme={}
  # 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
  ```

  <Warning>
    The `chroma` backend requires installing ChromaDB: `pip install chromadb`
  </Warning>
</ParamField>

<ParamField query="--summary-cache" type="path">
  Path to cache file for AI-generated summaries.

  ```bash theme={}
  helixcommit generate \
    --use-llm \
    --summary-cache .cache/summaries.json
  ```

  **Default:** `.helixcommit-cache/summaries.json`

  <Info>
    Caching reduces API costs by reusing previously generated summaries for unchanged commits.
  </Info>
</ParamField>

***

## Git Platform Options

### GitHub

<ParamField query="--github-token" type="string">
  GitHub personal access token for API requests.

  ```bash theme={}
  helixcommit generate --github-token ghp_...
  ```

  <Tip>
    Set the `GITHUB_TOKEN` environment variable instead of passing it as an argument for better security.
  </Tip>

  **Required permissions:**

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

  Create a token at [github.com/settings/tokens](https://github.com/settings/tokens)
</ParamField>

### GitLab

<ParamField query="--gitlab-token" type="string">
  GitLab personal access token for API requests.

  ```bash theme={}
  helixcommit generate --gitlab-token glpat-...
  ```

  <Tip>
    Set the `GITLAB_TOKEN` environment variable instead of passing it as an argument for better security.
  </Tip>

  **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](https://gitlab.com/-/user_settings/personal_access_tokens)
</ParamField>

### Bitbucket

<ParamField query="--bitbucket-token" type="string">
  Bitbucket App Password for API requests.

  ```bash theme={}
  helixcommit generate --bitbucket-token ...
  ```

  <Tip>
    Set the `BITBUCKET_TOKEN` environment variable instead of passing it as an argument for better security.
  </Tip>

  **Required permissions:**

  * Repositories: Read
  * Pull requests: Read

  Create an App Password at [bitbucket.org/account/settings/app-passwords](https://bitbucket.org/account/settings/app-passwords)
</ParamField>

***

## Environment Variables

<ResponseField name="GITHUB_TOKEN" type="string">
  GitHub personal access token for API authentication.

  ```bash theme={}
  export GITHUB_TOKEN=ghp_...
  helixcommit generate --unreleased
  ```

  Improves rate limits and enables access to private repositories.
</ResponseField>

<ResponseField name="OPENAI_API_KEY" type="string">
  OpenAI API key for AI summarization.

  ```bash theme={}
  export OPENAI_API_KEY=sk-...
  helixcommit generate --use-llm
  ```

  Required when using `--use-llm` with the OpenAI provider.
</ResponseField>

<ResponseField name="OPENROUTER_API_KEY" type="string">
  OpenRouter API key for AI summarization.

  ```bash theme={}
  export OPENROUTER_API_KEY=sk-or-...
  helixcommit generate --use-llm --llm-provider openrouter
  ```

  Required when using `--use-llm --llm-provider openrouter`.
</ResponseField>

<ResponseField name="GITLAB_TOKEN" type="string">
  GitLab personal access token for API authentication.

  ```bash theme={}
  export GITLAB_TOKEN=glpat-...
  helixcommit generate --unreleased
  ```

  Enables access to private GitLab projects and improves rate limits.
</ResponseField>

<ResponseField name="BITBUCKET_TOKEN" type="string">
  Bitbucket App Password for API authentication.

  ```bash theme={}
  export BITBUCKET_TOKEN=...
  helixcommit generate --unreleased
  ```

  Enables access to private Bitbucket repositories and improves rate limits.
</ResponseField>

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

<AccordionGroup>
  <Accordion title="Generate notes for CI/CD release" icon="rotate">
    ```bash theme={}
    #!/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
    ```
  </Accordion>

  <Accordion title="Preview unreleased changes with AI" icon="sparkles">
    ```bash theme={}
    export OPENAI_API_KEY=sk-...

    helixcommit generate \
      --unreleased \
      --use-llm \
      --openai-model gpt-4o-mini \
      --format markdown \
      --out preview.md
    ```
  </Accordion>

  <Accordion title="Generate HTML changelog for website" icon="globe">
    ```bash theme={}
    helixcommit generate \
      --since-tag v1.0.0 \
      --until-tag v2.0.0 \
      --format html \
      --out public/changelog.html \
      --no-merge-commits
    ```
  </Accordion>

  <Accordion title="Quick offline generation" icon="bolt">
    ```bash theme={}
    # Fast generation without external API calls
    helixcommit generate \
      --unreleased \
      --no-prs \
      --format text
    ```
  </Accordion>
</AccordionGroup>

***

## 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:

```bash theme={}
# Show general help
helixcommit --help

# Show help for generate command
helixcommit generate --help
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration guide" icon="gear" href="/configuration" color="#F6A02D">
    Learn about configuration options and customization
  </Card>

  <Card title="AI features" icon="sparkles" href="/ai-features" color="#F26419">
    Explore AI-powered summarization capabilities
  </Card>

  <Card title="Examples" icon="code" href="/examples" color="#0A6ACB">
    See real-world usage examples and patterns
  </Card>

  <Card title="Python API" icon="python" href="/api-reference/python-api" color="#0A6ACB">
    Use HelixCommit programmatically in Python
  </Card>
</CardGroup>