March 10, 2025"> May 13, 2026">
Skip to content

Getting Started

This guide will help you get up and running with GPTChangelog quickly.

Prerequisites

  • Python 3.8 or higher
  • Git repository
  • Either an OpenAI API key or a local codex login session

Installation

Install GPTChangelog using pip:

pip install gptchangelog

Configuration

Before using GPTChangelog, initialize configuration:

gptchangelog config init

This will prompt you for:

  1. Configuration type (global or project-specific)
  2. Provider choice (openai API key or codex ChatGPT subscription)
  3. The model to use (default: gpt-5.5)

If you want to use your Codex subscription, sign in once before initialization:

codex login
gptchangelog config init

Global vs. Project Configuration

  • Global configuration is stored in ~/.config/gptchangelog/config.ini and applies to all projects
  • Project configuration is stored in ./.gptchangelog/config.ini and only applies to the current project

Project configuration takes precedence over global configuration when both exist.

Basic Usage

Generate a Changelog

To generate a changelog from your latest tag to the current HEAD:

gptchangelog generate

This will:

  1. Find your latest git tag
  2. Fetch all commit messages since that tag
  3. Process and analyze the commit messages using OpenAI
  4. Determine the next version based on semantic versioning
  5. Generate a well-structured changelog
  6. Prepend it to your CHANGELOG.md file

Interactive Mode

For more control, use interactive mode:

gptchangelog generate --interactive

This allows you to review and edit the changelog before saving it.

Custom Commit Range

You can specify a custom range of commits:

gptchangelog generate --since v1.0.0 --to v2.0.0

Output to a Different File

By default, the changelog is prepended to CHANGELOG.md, but you can specify a different file:

gptchangelog generate --output docs/CHANGES.md

Dry Run

To preview the changelog without saving it:

gptchangelog generate --dry-run

Next Steps