Changesmith
Log inGet Started

Getting Started with Changesmith

This guide will help you set up Changesmith and generate your first changelog in under 5 minutes.

Choose Your Path

Changesmith works two ways:

  1. Web Dashboard — Best for teams, automatic triggers, one-click publishing
  2. CLI — Best for local development, CI pipelines, and automation

Web Dashboard Setup

Step 1: Sign Up

Go to changesmith.dev and click "Start for Free". Sign in with your GitHub account.

Step 2: Install the GitHub App

After signing in, you'll be prompted to install the Changesmith GitHub App:

  1. Click "Install GitHub App"
  2. Choose which repositories to grant access (you can start with just one)
  3. Confirm the permissions

Permissions requested:

  • Read access to commits, issues, pull requests, and repository metadata
  • Write access to releases (for publishing)

We never modify your source code.

Step 3: Generate Your First Changelog

Once connected, your repositories appear in the dashboard.

  1. Click on a repository
  2. Click "Generate Changelog"
  3. Select the version (or enter a custom one like v1.0.0)
  4. Click "Generate"

Changesmith will:

  • Fetch commits since your last release
  • Analyze diffs and PR descriptions
  • Generate a draft in your style

Step 4: Review and Publish

The generated draft appears in the editor. You can:

  • Edit the text directly
  • Reorder sections
  • Add or remove items
  • Change the formatting

When you're happy, click "Publish to GitHub" to create a GitHub Release.

CLI Setup

Installation

Install the CLI globally:

npm install -g @changesmith/cli

Verify it's installed:

changesmith --version

Authentication

Log in to Changesmith:

changesmith login

This opens your browser for device authentication. Once authenticated, your CLI is connected to your Changesmith account.

For CI/CD, use a token instead (see CI/CD Integration).

Initialize a Repository

Navigate to your git repository and run:

cd your-project
changesmith init

This creates a .changesmith.json config file with default settings.

Generate a Changelog

You have two ways to generate changelogs:

If your repository is connected to the Changesmith GitHub App:

# Generate for the latest tag
changesmith github

# Generate for a specific version
changesmith github v1.2.0

# Write directly to CHANGELOG.md
changesmith github v1.2.0 -w

# Generate and publish as a GitHub Release
changesmith github v1.2.0 --release

# Do both: update CHANGELOG.md and publish a release
changesmith github v1.2.0 -w --release

Option B: From local git history

No GitHub App required — works with any git repository:

# Generate for the latest tag
changesmith local

# Generate for a specific version
changesmith local v1.2.0

# Write directly to CHANGELOG.md
changesmith local v1.2.0 -w

# Preview commits before generating
changesmith local v1.2.0 --dry-run

No tags? Use autotag to create them from version bumps in your commit history:

# Preview what tags would be created
changesmith autotag --dry-run

# Create the tags
changesmith autotag

# Now generate changelogs as normal
changesmith local v1.2.0 -w

Example Output

## [1.2.0] - 2026-01-31

### Added

- Dark mode support across all pages (#142)
- Export to PDF functionality (#138)

### Fixed

- Login redirect issue on Safari (#145)
- Memory leak in real-time sync (#140)

### Changed

- Upgraded to React 19 for improved performance

Tips for Better Changelogs

Write Better Commit Messages

While Changesmith works with any commit style, clearer messages produce better results:

Okay:

fix bug

Better:

Fix login redirect issue on Safari mobile

Best:

fix(auth): resolve Safari redirect loop on mobile devices

Safari's ITP was blocking the OAuth callback. Added fallback
to use localStorage instead of cookies for the auth state.

Fixes #145

Use Pull Requests

Changesmith reads PR descriptions to understand context. A detailed PR description helps generate more accurate changelogs. (Applies to the github command; the local command uses commit messages and diffs only.)

Reference issue numbers in commits (#123) or PRs. Changesmith will fetch the issue title and description for additional context.

Customize the Style

If you have an existing CHANGELOG.md, Changesmith analyzes it to match your format and tone. The more history you have, the better it matches your style.

You can also set custom instructions:

changesmith config set customPrompt "Focus on user-facing changes. Keep each item to one sentence."

Next Steps