@changesmith/cli

Generate beautiful, AI-powered changelogs from your git history.

The Changesmith CLI connects to changesmith.dev to generate professional changelogs from your commits. Prompt logic stays server-side; the CLI handles local git operations and API communication.

Installation

npm install -g @changesmith/cli
# or
pnpm add -g @changesmith/cli
# or run without installing
npx @changesmith/cli

Requires Node.js 20+.

Quick Start

# Initialize in your repository
changesmith init

# Log in to Changesmith
changesmith login

# Generate a changelog (via GitHub App)
changesmith github

# Or generate from local git history (no GitHub App needed)
changesmith local

Commands

changesmith init

Initialize Changesmith in the current repository. Creates a .changesmith.json config file.

changesmith init
changesmith init --force  # Overwrite existing config

changesmith login

Authenticate with Changesmith. Uses device authorization flow by default.

# Interactive (opens browser)
changesmith login

# For CI/automation, use a pre-generated token
changesmith login --token YOUR_TOKEN

changesmith logout

Log out from Changesmith.

changesmith logout
changesmith logout --clear-stored  # Remove stored creds even when env var is set

changesmith github

Generate a changelog via the GitHub App. Requires your repository to be connected via the Changesmith GitHub App.

# Generate for latest tag
changesmith github

# Generate for a specific version
changesmith github v1.2.0

# Specify a commit range
changesmith github v1.2.0 --from v1.1.0

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

# Output to a custom file
changesmith github v1.2.0 -o release-notes.md

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

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

Options:

| Flag | Description | | --------------------- | ------------------------------------------------------------------ | | --from <tag> | Starting tag/commit (defaults to previous tag) | | --to <ref> | Ending ref (defaults to the version tag) | | -o, --output <file> | Write to a specific file | | -w, --write | Prepend to CHANGELOG.md | | -r, --release | Publish as a GitHub Release after generation (combines with -w/-o) |

Alias: changesmith generate works as a hidden alias for changesmith github.

changesmith autotag

Create git tags from version bumps in commit history. Scans package.json, Cargo.toml, and pyproject.toml for version changes.

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

# Create the tags
changesmith autotag

# Create and push to remote
changesmith autotag --push

# Only scan recent history
changesmith autotag --after v1.0.0

Options:

| Flag | Description | | ----------------- | ---------------------------------------------------- | | --dry-run | Show what tags would be created without creating them | | --after <ref> | Only scan commits after this ref | | --prefix <str> | Tag prefix (default: v) | | --push | Push created tags to the origin remote |

changesmith local

Generate a changelog from local git commits. No GitHub App required — commits and diffs are read from your local repository.

# Generate for latest tag
changesmith local

# Generate for a specific version
changesmith local v1.2.0

# Specify a starting point
changesmith local v1.2.0 --from v1.1.0

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

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

No tags? Use changesmith autotag first to create tags from version bumps.

Options:

| Flag | Description | | --------------------- | ---------------------------------------------------------- | | --from <ref> | Starting ref (defaults to previous tag) | | --to <ref> | Ending ref (defaults to HEAD) | | --dry-run | List commits in the range without generating | | -o, --output <file> | Write to a specific file | | -w, --write | Prepend to CHANGELOG.md (aborts if version already exists) |

Limits: 500 commits max, 3 MB total diff size. Diffs from oldest commits are skipped if the size limit is exceeded.

changesmith status

Show Changesmith status for the current repository.

changesmith status

Displays git info, project config, authentication state, and plan details.

changesmith config

View or modify configuration.

# Show all config (project + user)
changesmith config show
changesmith config show --project  # Project only
changesmith config show --user     # User only

# Get a specific value
changesmith config get excludeTypes
changesmith config get apiUrl --global

# Set a value
changesmith config set excludeTypes "chore,style,ci,docs"
changesmith config set defaultBranch main
changesmith config set customPrompt "Focus on user-facing changes."

# Set user config
changesmith config set apiUrl https://api.changesmith.dev --global

# Reset project config to defaults
changesmith config reset --force

Configuration

Project Config (.changesmith.json)

Repository-specific settings stored in your project root:

{
  "version": 1,
  "defaultBranch": "main",
  "excludeTypes": ["chore", "style", "ci"],
  "includeScopes": [],
  "excludeScopes": [],
  "styleGuide": "",
  "customPrompt": ""
}

| Key | Description | | --------------- | --------------------------------------------- | | version | Config version (always 1) | | defaultBranch | Default branch for comparisons | | excludeTypes | Commit types to exclude (e.g., chore, ci) | | includeScopes | Only include these scopes (empty = all) | | excludeScopes | Exclude these scopes | | styleGuide | Style guide name for generation | | customPrompt | Custom instructions for AI generation |

User Config (~/.changesmith)

Global settings:

| Key | Description | | -------- | ----------------------------------------------------- | | apiUrl | API endpoint (default: https://api.changesmith.dev) | | token | Auth token (set via changesmith login) |

Environment Variables

Environment variables take precedence over stored configuration. Empty or whitespace-only values are ignored.

| Variable | Description | | --------------------- | --------------------------------------- | | CHANGESMITH_TOKEN | Auth token (no login needed when set) | | CHANGESMITH_API_URL | API endpoint override |

Security: Never commit tokens to version control. Use your CI platform's secrets management (e.g., GitHub Secrets, GitLab CI/CD variables).

CI/CD Usage

Set CHANGESMITH_TOKEN as a secret environment variable. No interactive login step is required.

GitHub Actions

name: Changelog
on:
  push:
    tags: ['v*']

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate changelog
        env:
          CHANGESMITH_TOKEN: ${{ secrets.CHANGESMITH_TOKEN }}
        run: npx @changesmith/cli github ${{ github.ref_name }} -w --release

Using local in CI

If your repository isn't connected via the GitHub App:

- name: Generate changelog
  env:
    CHANGESMITH_TOKEN: ${{ secrets.CHANGESMITH_TOKEN }}
  run: npx @changesmith/cli local ${{ github.ref_name }} -w

Generate an API token from the Changesmith dashboard.

github vs local

| Feature | github | local | | ------------------- | ------------------ | -------------------- | | Requires GitHub App | Yes | No | | Data source | GitHub API | Local git repository | | PR/issue context | Yes | No | | --release flag | Yes | No | | --dry-run flag | No | Yes | | Works unpushed | No | Yes | | Max commits | Unlimited | 500 | | Max diff size | Unlimited | 3 MB |

Both commands require git tags. Use changesmith autotag to create tags from version bumps if your repo doesn't have them.

Requirements

• Node.js 20+
• Git repository
• Changesmith account (sign up free)

Links

• Changesmith Dashboard
• Documentation
• CLI Reference
• GitHub

License

MIT