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

-
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 | shWindows: 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 | iexLinux: 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 | shIt downloads Bumpwise from this website, checks that the file is the published one, and adds a
bumpwisecommand. 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. -
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/orbuild/); it never runs your build. -
Check it
In a terminal, in your library's folder:
bumpwise checkJust installed? Open a new terminal window first, so that it finds the
bumpwisecommand.
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
| Option | What it does |
|---|---|
--project DIR | The library's folder. Default: the current folder. In a multi-module build, the folder of the module you publish. |
--artifact GROUP:ARTIFACT | The published library, for example com.acme:acme-core. Default: read from the build. Needed when the build computes it. |
--current PATH | The build to check: a jar or a folder of classes. Repeat it for several. Default: found in target/ or build/. |
--classpath PATHS | Jars 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 PACKAGE | A 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 V | The 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 V | Compare with this published version instead. |
--repository URL | A public Maven repository or a mirror of Maven Central. Default: Maven Central. |
--format F | text (default), json for scripts, markdown for a pull request comment or job summary, sarif for GitHub code scanning. Short forms: --json, --markdown, --sarif. |
--changelog | Also print a changelog draft (Markdown) with the text output. |
--cache DIR | Where 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
| Code | Meaning |
|---|---|
0 | Compatible, or the breaking changes are allowed by the declared version (a new major version). Also when the library was never published. |
1 | Breaking changes that the declared version does not allow, or breaking changes with no version declared. |
2 | Usage 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:
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 inbuild/publications/, or~/.m2; pass--classpathwhen 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 REFchecks 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 checkfinds the coordinates, version and build output on its own;--format json|markdown|sarif;bumpwise mcp, the MCP server for AI agents, with thecheck_api_compatibilitytool and therelease_checkprompt;--excludefor 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.