Free · Java 17+ · Terminal, CI and AI agents

Bumpwise command line

Before you release, one command tells you whether your build breaks the last published version of your library, and which version number it needs. Before you upgrade a dependency, it shows which lines of your code the new version breaks. In a terminal, in CI, or for your AI coding agent. Free for everyone, commercial use included.

Get started

Get started

Three steps, about two minutes. You need Java 17 or later, which you already have if you build Java or Kotlin libraries.

A real session in 3 minutes: the installer, every output format, and Claude Code catching a breaking change over MCP. The video plays from YouTube, which loads only when you press play.
  1. Install

    macOS: press ⌘ Space, type Terminal and press Enter. Copy this command, paste it in the Terminal window with ⌘ V and press Enter:

    curl -fsSL https://gilware.com/bumpwise/cli/install.sh | sh

    Windows: press the Windows key, type PowerShell and press Enter. Copy this command, paste it in the PowerShell window with Ctrl V and press Enter:

    irm https://gilware.com/bumpwise/cli/install.ps1 | iex

    Linux: open a terminal (Ctrl Alt T on most systems). Copy this command, paste it with Ctrl Shift V and press Enter:

    curl -fsSL https://gilware.com/bumpwise/cli/install.sh | sh

    It downloads Bumpwise from this website, checks that the file is the published one, and adds a bumpwise command. If you use Claude Code, it asks whether to set Bumpwise up there too. Nothing else is changed, and nothing is sent anywhere. If it says Java is missing, install Java 17 or later (for example from adoptium.net) and run it again.

  2. Build your library

    Build it the way you usually do, in your IDE or in a terminal. Bumpwise reads what the build produced (in target/ or build/); it never runs your build.

  3. Check it

    In a terminal, in your library's folder:

    bumpwise check

    Just installed? Open a new terminal window first, so that it finds the bumpwise command.

Reading the result

Bumpwise finds your library's name and version in pom.xml or the Gradle build, downloads the release it follows from Maven Central (here 1.3.0, the latest before 1.4.0), and compares the public API:

Artifact: com.acme:acme-core (declared version 1.4.0-SNAPSHOT)
Compared with published version: 1.3.0
Verdict: BREAKS THE API (requires MAJOR, next version 2.0.0)

Breaking changes (1):
- com.acme.Client#fetch(String): signature changed to fetch(String, int) [Binary incompatible]
  Compatible alternative: Add fetch(String, int) as a new method and keep fetch(String) as @Deprecated, delegating to it: the change becomes a MINOR one.

Other changes: 1 addition

Warning: pom.xml declares 1.4.0-SNAPSHOT, but the changes require at least 2.0.0.
  • Compatible: users can upgrade without changing their code. Release it with the version you planned.
  • Breaks the API: users' code would stop compiling or crash. Either follow the compatible alternative (here: keep the old method), or release it as the next major version (here 2.0.0).
  • Not sure what to do, or a result looks wrong? Write to hello@gilware.com with the output.

Before you upgrade a dependency

New in 1.1.0, for any Java or Kotlin project, library or application. When a new version of a dependency comes along (from Dependabot, Renovate, your AI agent or yourself), Bumpwise lists the places in your code that it breaks. Build your project, then run:

bumpwise upgrade com.google.guava:guava:21.0

Bumpwise reads the version you use now from pom.xml, build.gradle(.kts) or gradle/libs.versions.toml, downloads both versions, compares them, and looks for each breaking change in your compiled classes. Leave out the version to check the latest release. Here is a real run on a small app that uses Guava 18.0:

com.google.guava:guava 18.0 -> 21.0: breaks 2 places in this project (2 breaking changes used).

com.google.common.base.Objects.ToStringHelper: class removed
  src/main/java/app/Person.java:11  app.Person uses it
com.google.common.base.Objects#toStringHelper(Object): removed
  src/main/java/app/Person.java:11  app.Person calls it

13 other breaking changes in 21.0 do not affect this project.

Checked the compiled classes: uses through reflection, and code that is not compiled, are not seen.

It finds calls (also through your own subclasses), method references, field reads and writes, subclasses, overrides, and classes that do not implement a new abstract method. Changes that only the compiler notices, such as a new checked exception, are marked: code that is already compiled keeps running, but it no longer compiles. Exit code 0 means the upgrade is safe for this project, 1 that it breaks places in it, and 2 that Bumpwise could not tell.

Dependabot and Renovate: bumpwise upgrade --changed-since origin/main finds every dependency version the pull request changed and checks each one. See In CI.

AI agents: the MCP server has a second tool for this, check_dependency_upgrade. Ask your agent, for example: “Can I upgrade Guava to 21.0?” To make it check before every version change, add this line to CLAUDE.md or AGENTS.md:

Before changing a dependency's version, build and call check_dependency_upgrade, then fix the places it lists.

Use it with your AI agent

Coding agents change public APIs without noticing. With Bumpwise, the agent can ask, after building, whether its change breaks your last release, and get the compatible alternative.

Claude Code: the installer sets it up when you answer yes. To check, run claude mcp list: bumpwise should show as connected. Then ask the agent, for example: “Did my change break the API of the last release?”, or type /mcp__bumpwise__release_check: the agent builds the library, runs the check and explains what the release needs.

To make the agent check on its own, add this line to your project's CLAUDE.md or AGENTS.md:

After changing a public API, build and call check_api_compatibility before committing; prefer the compatible alternative it suggests.

Cursor, VS Code, Codex and other agents: see MCP setup below.

Update or uninstall

Update: run the install command again. Your setup, including Claude Code, keeps working. New versions are listed under Versions.

Uninstall, on macOS and Linux:

rm -rf ~/.local/share/bumpwise ~/.local/bin/bumpwise ~/.cache/bumpwise

On Windows (PowerShell):

Remove-Item -Recurse "$env:LOCALAPPDATA\Bumpwise"

If you set up Claude Code, also run claude mcp remove -s user bumpwise. On macOS and Linux, the installer may have added two lines starting with # Bumpwise command line to your shell profile (~/.zshrc, ~/.bashrc or ~/.profile); you can delete them.

Advanced

Everything below is optional: options, CI, other agents and installing by hand.

Options

OptionWhat it does
--project DIRThe library's folder. Default: the current folder. In a multi-module build, the folder of the module you publish.
--artifact GROUP:ARTIFACTThe published library, for example com.acme:acme-core. Default: read from the build. Needed when the build computes it.
--current PATHThe build to check: a jar or a folder of classes. Repeat it for several. Default: found in target/ or build/.
--classpath PATHSJars the build depends on, separated by : (; on Windows). Needed only when Bumpwise cannot read them from pom.xml, the POM Gradle generates in build/publications/, or ~/.m2 (after mvn install or ./gradlew publishToMavenLocal). It tells a class that moved into a dependency from a removed one.
--exclude PACKAGEA package (with its subpackages) or class that is not public API, for example com.acme.internal. Its changes are left out, and one line at the end of the result says how many. Repeat it, or separate several with commas; * and ** work as in .bumpwise.yml. The MCP tool takes the same list as exclude.
--version VThe version your build declares (default: read from the build). It picks the release to compare with (the latest one before it, so a 1.4.0-SNAPSHOT maintenance build is compared with 1.3.x even when 2.0.0 is out) and is checked against the changes.
--against VCompare with this published version instead.
--repository URLA public Maven repository or a mirror of Maven Central. Default: Maven Central.
--format Ftext (default), json for scripts, markdown for a pull request comment or job summary, sarif for GitHub code scanning. Short forms: --json, --markdown, --sarif.
--changelogAlso print a changelog draft (Markdown) with the text output.
--cache DIRWhere downloaded releases are kept. Default: ~/.cache/bumpwise. Released versions never change, so a second run downloads nothing.

bumpwise --help prints the same list. Where Bumpwise looks for the build output: target/<artifactId>-<version>.jar or target/classes (Maven); build/libs/<name>-<version>.jar, build/classes/java/main or build/classes/kotlin/main (Gradle). It reads the name and version from pom.xml, gradle.properties (GROUP/VERSION_NAME/POM_ARTIFACT_ID or group/version) or plain group = "..." and version = "..." lines; when it cannot, the message says which option to pass.

Exit codes

CodeMeaning
0Compatible, or the breaking changes are allowed by the declared version (a new major version). Also when the library was never published.
1Breaking changes that the declared version does not allow, or breaking changes with no version declared.
2Usage or setup error: wrong options, no build output (build first), coordinates not found, release not found, network error. The message says what to do.

In CI

Run it after the build step, so a pull request that breaks the API without a major version fails. GitHub Actions, for a Gradle library (pinned to one version, with its checksum):

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: 21
- run: ./gradlew jar
- name: API compatibility
  run: |
    curl -fsSLO https://gilware.com/bumpwise/cli/bumpwise-1.1.0.jar
    echo "a26e3bf8894f7640acbae604502b0341cf1e894bd084737ba3bc1eae2d65b976  bumpwise-1.1.0.jar" | sha256sum -c
    java -jar bumpwise-1.1.0.jar check --markdown >> "$GITHUB_STEP_SUMMARY"

The job fails on breaking changes the declared version does not allow, and the summary of the run shows the verdict, the next version and each change. Use --sarif instead to send the changes to GitHub code scanning, or --json to process them in a script. Any other CI works the same way; use --cache on a cached folder to avoid downloading the release again on every run.

To check dependency updates in pull requests (from Dependabot, Renovate or a person), for a Maven project. The checkout needs the history, so that Bumpwise can read the build files of the target branch:

on: pull_request
jobs:
  dependencies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
      - run: mvn -B -q compile
      - name: What the dependency updates break
        run: |
          curl -fsSLO https://gilware.com/bumpwise/cli/bumpwise-1.1.0.jar
          echo "a26e3bf8894f7640acbae604502b0341cf1e894bd084737ba3bc1eae2d65b976  bumpwise-1.1.0.jar" | sha256sum -c
          java -jar bumpwise-1.1.0.jar upgrade --changed-since origin/${{ github.base_ref }} --markdown >> "$GITHUB_STEP_SUMMARY"

The job fails when an update breaks your code, and the summary lists each place. With Gradle, build with ./gradlew classes instead. With --sarif and GitHub's upload-sarif action, code scanning shows each place on the pull request.

MCP setup for other agents

bumpwise mcp runs an MCP server on stdio with two tools: check_api_compatibility, the same tool and answer as in the IntelliJ plugin without an IDE, and check_dependency_upgrade, which lists what a dependency upgrade breaks in the project. In Cursor, VS Code, Codex or any MCP client, add a stdio server with the command java and these arguments: -jar, the full path to the jar, and mcp. The jar is at ~/.local/share/bumpwise/bumpwise.jar on macOS and Linux (write the full path, for example /Users/you/.local/share/bumpwise/bumpwise.jar: most clients do not expand ~) and at %LOCALAPPDATA%\Bumpwise\bumpwise.jar on Windows. Claude Code by hand, on macOS and Linux:

claude mcp add -s user bumpwise -- java -jar ~/.local/share/bumpwise/bumpwise.jar mcp

“Failed” or “Connection closed” in claude mcp list almost always means the path to the jar is wrong: run the installer again and answer yes. Optional arguments after mcp: --project DIR (the folder the tool checks by default; otherwise the folder the agent runs in), --repository URL and --cache DIR. The arguments of check_api_compatibility are all optional: project (a module folder), artifact, current, version, against and includeChangelog. check_dependency_upgrade takes dependency (GROUP:ARTIFACT, required), to, from, project and current. Both read compiled classes, so the agent builds first. The server supports MCP 2026-07-28 and the earlier handshake versions back to 2024-11-05.

Install by hand

Bumpwise is a single jar that runs on any Java 17 or later; there is nothing else to install. Version 1.1.0, 21 November 2026, 3.6 MB:

Download bumpwise-1.1.0.jar

SHA-256 (file):
a26e3bf8894f7640acbae604502b0341cf1e894bd084737ba3bc1eae2d65b976

Run it with java -jar bumpwise-1.1.0.jar check. The install scripts (install.sh, install.ps1) do the same download and check; read them before running them if you prefer. They take BUMPWISE_NO_PROMPT=1 to skip the questions, and BUMPWISE_DIR (and BUMPWISE_BIN on macOS and Linux) to install elsewhere.

What it checks

  • Java and Kotlin libraries (JVM bytecode), published on Maven Central or another public Maven repository.
  • The same rules as the Bumpwise plugin: removed or changed classes, methods and fields, narrowed visibility, new abstract methods, changed supertypes and the other binary and source incompatibilities, plus the next semantic version.
  • Supertypes and exceptions from your dependencies: the dependencies listed in the published POM are downloaded too, so inherited members are followed.
  • Classes that moved into a dependency of the new build, for example into an artifact of their own, are reported as moved, not removed. Bumpwise reads the new build's dependencies from pom.xml, the POM Gradle generates in build/publications/, or ~/.m2; pass --classpath when none of them is there.
  • Every public package, internal ones included, unless you leave them out with --exclude.

Not in the command line: private repositories that need credentials, the .bumpwise.yml team policy, TypeScript, Go, PHP and Rust, and warnings while you type. Those are in the IDE plugin.

Versions

  • 1.1.0 (21 November 2026): bumpwise upgrade GROUP:ARTIFACT[:VERSION] lists the places in a project that a dependency upgrade breaks, at file and line; --changed-since REF checks every dependency a pull request changed; the MCP server has a second tool, check_dependency_upgrade.
  • 1.0.0 (19 November 2026): first release. bumpwise check finds the coordinates, version and build output on its own; --format json|markdown|sarif; bumpwise mcp, the MCP server for AI agents, with the check_api_compatibility tool and the release_check prompt; --exclude for packages that are not API.

Privacy

The command line runs on your computer and sends nothing to Gilware: no telemetry, no account, no license key. It only downloads published metadata and packages from the repository it is given (Maven Central by default), identified as Bumpwise (+https://gilware.com/bumpwise/). See the privacy policy.

License

Free for any use, including commercial use, on any number of machines. You may share unmodified copies, for example in a CI image. The terms are also inside the jar (META-INF/LICENSE.txt), with the licenses of the open source components it bundles (META-INF/THIRD-PARTY-NOTICES.txt).

Questions or a wrong result? Write to hello@gilware.com with the command you ran.

Find out while you type, not at release time

The Bumpwise plugin for IntelliJ IDEA and Android Studio warns you in the editor the moment a change breaks your last release, and fixes it with Alt+Enter. Free for Java libraries on Maven Central.