CLI Reference

Complete reference for the Changesmith CLI.

Installation

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

Requires Node.js 20 or later.

Authentication

The CLI requires authentication to generate changelogs. All generation happens server-side via the Changesmith API.

Interactive login (recommended for local use):

changesmith login

Token-based (recommended for CI/CD):

# Via environment variable (no login step needed)
export CHANGESMITH_TOKEN=your-token

# Or via --token flag
changesmith login --token YOUR_TOKEN

Generate an API token from the Changesmith dashboard.

Commands

`changesmith init`

Initialize Changesmith in the current git repository. Creates a .changesmith.json config file with defaults detected from your repository.

changesmith init [options]

Options:

| Flag | Description | | --- | --- | | -f, --force | Overwrite existing config |

What it does:

Detects the git repository and default branch
Resolves the GitHub remote URL
Creates .changesmith.json with defaults

Example:

$ changesmith init
✔ Git repository detected
✔ Created .changesmith.json

Changesmith initialized successfully!

Repository: your-org/your-repo
Default branch: main

Next steps:
  1. Log in to Changesmith:
     changesmith login

  2. Generate a changelog:
     changesmith github v1.0.0

`changesmith github`

Generate a changelog via the GitHub App. This command uses the Changesmith GitHub App installation to read commits, PRs, and issues directly from GitHub — no local git history needed beyond tag detection.

This is the recommended command when your repository is connected to Changesmith via the GitHub App.

changesmith github [version] [options]

Arguments:

| Argument | Description | | --- | --- | | version | Target version tag (e.g., v1.0.0). Defaults to latest tag. |

Options:

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

Examples:

# Generate for latest tag, print to stdout
changesmith github

# Generate for a specific version
changesmith github v2.0.0

# Custom commit range
changesmith github v2.0.0 --from v1.5.0

# Write to CHANGELOG.md
changesmith github v2.0.0 -w

# Write to a custom file
changesmith github v2.0.0 -o release-notes.md

# Generate and publish as GitHub Release in one step
changesmith github v2.0.0 --release

# Generate, update CHANGELOG.md, and publish as GitHub Release
changesmith github v2.0.0 -w --release

How it works:

Detects the repository from your git remote
Looks up the repository in Changesmith (requires GitHub App installation)
Queues a generation job on the server
Polls for completion (up to 10 minutes)
Outputs the result (stdout, file, or CHANGELOG.md)
Optionally publishes as a GitHub Release

Alias: changesmith generate is a hidden alias for changesmith github for backwards compatibility.

`changesmith autotag`

Create git tags from version bumps found in commit history. This scans your commits for changes to package.json, Cargo.toml, or pyproject.toml and creates tags wherever the version field was bumped.

Useful for forks, monorepos, or any repository that tracks versions in package files but doesn't have git tags.

changesmith autotag [options]

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 |

Examples:

# 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

# Use a custom tag prefix
changesmith autotag --prefix release-

Example output (dry-run):

Scanning commit history for version bumps...

  abc1234 2026-01-15  package.json  1.0.0 → 1.1.0  (tag: v1.1.0)
  def5678 2026-02-01  package.json  1.1.0 → 1.2.0  (tag: v1.2.0)
  ghi9012 2026-02-20  Cargo.toml    0.8.0 → 0.9.0  (tag: v0.9.0)

3 tags would be created. Run without --dry-run to create them.

How it works:

Walks the commit history (or from --after ref)
Finds commits that changed package.json, Cargo.toml, or pyproject.toml
Compares the version field between each commit and its parent
Skips versions where a tag already exists
Creates lightweight tags at the version-bump commits

`changesmith local`

Generate a changelog from local git commits. This command collects commits and diffs from your local repository and sends them to the Changesmith API for generation — no GitHub App installation required.

Use this when your repository isn't connected via the GitHub App, or when you want to generate from local (unpushed) commits.

changesmith local [version] [options]

Arguments:

| Argument | Description | | --- | --- | | version | Version label for the changelog heading (e.g., v1.0.0). Defaults to latest tag. |

Options:

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

Examples:

# Generate for latest tag
changesmith local

# Generate for a specific version
changesmith local v1.2.0

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

# Preview which commits would be included 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 in your commit history. Once tags exist, local (and github) work seamlessly.

How it works:

Determines the version label (from argument or latest tag)
Determines the commit range (--from/--to or previous tag)
Collects commits between the refs from local git history
Gathers diffs for each commit (up to 3 MB total, 500 commits max)
Reads your existing CHANGELOG.md for style matching
Reads .changesmith.json for custom instructions
Sends everything to the Changesmith API for generation
Polls for completion and outputs the result

Limits:

| Limit | Value | | --- | --- | | Max commits | 500 | | Max total diff size | 3 MB | | Generation timeout | 10 min |

If your diff exceeds the size limit, the oldest commits' diffs are skipped (commits are still included, just without diff context).

Shallow clones: If your repository is a shallow clone (common in CI), you'll see a warning. Run git fetch --unshallow for complete history.

`changesmith login`

Authenticate with Changesmith. Uses the device authorization flow by default — you'll be shown a code to enter in your browser.

changesmith login [options]

Options:

| Flag | Description | | --- | --- | | --token <token> | Use a pre-generated auth token (for CI/automation) |

Interactive login:

$ changesmith login
Changesmith Login

To authenticate, visit:

  https://changesmith.dev/auth/device

And enter this code:

  ABCD-1234

⠋ Waiting for authentication...
✔ Logged in as @yourname

Token-based login (for CI):

changesmith login --token cs_abc123...

The token is validated against the API before being saved. If CHANGESMITH_TOKEN is already set as an environment variable, you'll be warned that the env var takes precedence over stored credentials.

`changesmith logout`

Remove stored credentials.

changesmith logout [options]

Options:

| Flag | Description | | --- | --- | | --clear-stored | Remove stored credentials even when CHANGESMITH_TOKEN is set |

Behavior:

If authenticated via CHANGESMITH_TOKEN env var: prints instructions to unset it
If authenticated via stored credentials: clears them
With --clear-stored: removes stored credentials regardless of env var state

`changesmith status`

Show Changesmith status for the current repository, including git info, configuration, and authentication state.

changesmith status

Example:

$ changesmith status
Changesmith Status

Git repository: Yes
Repository:     your-org/your-repo
Latest tag:     v1.6.7
Total tags:     23

Project config: .changesmith.json
Excluded types: chore, style, ci

Logged in:      yes
User:           yourname
Plan:           business

Run `changesmith generate` to create a changelog.

`changesmith config`

View or modify project and user configuration. Project config is stored in .changesmith.json (per-repository). User config is stored in ~/.changesmith (global).

`changesmith config show`

Display current configuration.

changesmith config show [options]

| Flag | Description | | --- | --- | | --project | Show project config only | | --user | Show user config only |

`changesmith config get <key>`

Get a specific configuration value.

changesmith config get <key> [options]

| Flag | Description | | --- | --- | | --global | Read from user config instead of project config |

Project config keys: version, defaultBranch, excludeTypes, includeScopes, excludeScopes, styleGuide, customPrompt

User config keys: apiUrl

`changesmith config set <key> <value>`

Set a configuration value.

changesmith config set <key> <value> [options]

| Flag | Description | | --- | --- | | --global | Write to user config instead of project config |

For array values (excludeTypes, includeScopes, excludeScopes), pass a comma-separated string:

changesmith config set excludeTypes "chore,style,ci,docs"

`changesmith config reset`

Reset project config to defaults.

changesmith config reset [options]

| Flag | Description | | --- | --- | | -f, --force | Skip confirmation |

Examples:

# Show all config
changesmith config show

# Get a specific project value
changesmith config get excludeTypes

# Set the API URL (user config)
changesmith config set apiUrl https://api.changesmith.dev --global

# Set excluded commit types
changesmith config set excludeTypes "chore,style,ci,test"

# Set custom AI instructions
changesmith config set customPrompt "Focus on user-facing changes. Use simple language."

# Reset project config
changesmith config reset --force

Configuration

Project Config (`.changesmith.json`)

Repository-specific settings. Created by changesmith init.

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

| Key | Type | Description | | --- | --- | --- | | version | number | Config schema version (always 1) | | defaultBranch | string | Default branch for comparisons | | excludeTypes | string[] | Conventional commit types to exclude from changelog | | includeScopes | string[] | Only include these scopes (empty = all) | | excludeScopes | string[] | Exclude commits with these scopes | | styleGuide | string | Style guide name for generation | | customPrompt | string | Custom instructions for AI generation |

See Configuration for detailed examples of each option.

User Config (`~/.changesmith`)

Global settings that apply across all repositories.

| Key | Type | Description | | --- | --- | --- | | apiUrl | string | API endpoint (default: https://api.changesmith.dev) | | token | string | Auth token (set via changesmith login, not edited directly) | | userId | string | User ID (set automatically on login) |

Environment Variables

Environment variables take precedence over stored configuration.

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

Empty or whitespace-only values are ignored, falling back to stored config.

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

`github` vs `local`

| Feature | github | local | | --- | --- | --- | | Requires GitHub App | Yes | No | | Reads from | GitHub API (commits, PRs, issues) | Local git history | | Diff source | GitHub comparison API | git show (local) | | Works with unpushed code | No | Yes | | --release flag | Yes | No | | --dry-run flag | No | Yes | | PR/issue context | Yes | No | | Style matching | Server-side | Via existing CHANGELOG.md | | Max commits | Unlimited (paginated) | 500 | | Max diff size | Unlimited | 3 MB |

When to use github: Your repository is connected via the GitHub App and you want the richest context (PRs, issues, full diffs).

When to use local: You haven't installed the GitHub App, you're working with unpushed commits, or you're in a restricted environment.

No tags? Both commands require git tags. Use changesmith autotag to create tags from version bumps in your commit history.

Exit Codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Error (see message) |

Troubleshooting

"Not a git repository"

Run changesmith from a directory that contains a .git directory, or from any subdirectory of a git repository.

"Error: Not logged in"

Authenticate first:

# Interactive
changesmith login

# Or set the environment variable
export CHANGESMITH_TOKEN=your-token

"Repository not connected to Changesmith"

The github command requires your repository to be connected via the GitHub App. Either:

Install the GitHub App from the dashboard
Or use changesmith local instead (no GitHub App required)

"No version specified and no tags found"

This occurs when no tags exist in the repository. If your project tracks versions in package files, use autotag to create tags automatically:

changesmith autotag --dry-run  # Preview
changesmith autotag             # Create tags

Or create a tag manually:

git tag v1.0.0
git push origin v1.0.0

Or specify the version and range explicitly:

changesmith local v1.0.0 --from HEAD~50

"Could not determine the start of the commit range"

The CLI couldn't find a previous tag to use as the starting point. Specify it manually:

changesmith local v1.0.0 --from HEAD~50
changesmith local v1.0.0 --from abc1234

Or use autotag to create tags from version bumps in your history:

changesmith autotag

"Version X already exists in CHANGELOG.md"

The -w flag detected that your CHANGELOG.md already has a section for this version. This prevents duplicate entries. Either:

Remove the existing section from CHANGELOG.md first
Or write to a different file with -o:

changesmith local v1.0.0 -o release-notes.md

"No commits found in the specified range"

The commit range returned no commits. Verify your --from and --to values:

# Check what git sees
git log v1.0.0..v2.0.0 --oneline

"Payload too large"

The local command hit the 3 MB diff size limit. Try a smaller commit range:

changesmith local v2.0.0 --from v1.9.0  # Instead of --from v1.0.0

"This is a shallow clone"

CI environments often use shallow clones. Fetch the full history:

git fetch --unshallow

Or in GitHub Actions:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

CLI Reference

Installation

Authentication

Commands

changesmith init

changesmith github

changesmith autotag

changesmith local

changesmith login

changesmith logout

changesmith status

changesmith config

changesmith config show

changesmith config get <key>

changesmith config set <key> <value>

changesmith config reset

Configuration

Project Config (.changesmith.json)

User Config (~/.changesmith)

Environment Variables

github vs local

Exit Codes

Troubleshooting

"Not a git repository"

"Error: Not logged in"

"Repository not connected to Changesmith"

"No version specified and no tags found"

"Could not determine the start of the commit range"

"Version X already exists in CHANGELOG.md"

"No commits found in the specified range"

"Payload too large"

"This is a shallow clone"

`changesmith init`

`changesmith github`

`changesmith autotag`

`changesmith local`

`changesmith login`

`changesmith logout`

`changesmith status`

`changesmith config`

`changesmith config show`

`changesmith config get <key>`

`changesmith config set <key> <value>`

`changesmith config reset`

Project Config (`.changesmith.json`)

User Config (`~/.changesmith`)

`github` vs `local`