The right route is the one where you can fix an exact version, fetch it from a source you control and run it the same way on every machine. Docker with a pinned tag or digest, or a JAR from Maven Central at a fixed version, usually fit well. Convenience installers suit laptops.
The routes the docs list
The installation page documents these ways to get the CLI: the npm wrapper, Homebrew on macOS, Scoop on Windows, PyPI, Docker, a direct JAR download, JBang and a Bash launcher script. The JAR needs a Java 11 runtime at minimum, according to the page.
Comparison for repeatability
| Route | Pin an exact version | Needs Java on the machine | Main caution |
|---|---|---|---|
| npm wrapper | Yes, via the version manager or a dev dependency | Wrapper runs the JAR | Global install gives "latest" by default |
| Homebrew | The docs show a plain install command with no version | Handled by the formula | Laptop friendly, poor for CI pinning |
| Scoop | Similar to Homebrew | Java may need separate install | Windows convenience |
| PyPI package | Pin in the requirements file | Needs a java executable, or a bundled option | Check what the package version maps to |
| Docker image | Yes, by tag, better by digest | No | Do not run the untagged form in CI |
| Direct JAR | Yes, version in the URL | Yes | You must verify and cache the download |
| JBang | Maven coordinates, so a version can be set | Handled by JBang | The docs example uses LATEST, change it |
| Bash launcher | Via an environment variable | Yes | Fetches newest by default |
The notes about defaults come straight from the docs' own examples: the npm global command installs the latest version, the JBang example uses the LATEST keyword, and the launcher checks for the newest release.
How to choose
- CI that must be repeatable. Use Docker by digest, or the JAR at a fixed version served from your own artifact store.
- A JavaScript or TypeScript project. The npm wrapper as a dev dependency keeps the version in your lockfile alongside other tools.
- A Java project. Use the Maven or Gradle plugin with an explicit plugin version, as the plugins page shows.
- Developer laptops. Any convenient installer is fine, as long as CI is the source of truth and checks the version.
Whatever you choose
- Write the version down in one file that CI and developers both read.
- Prefer fetching through your own mirror or registry so a changed upstream does not change your build.
- Fail the build when the reported version differs from the recorded one.
- Remember that pinning the tool does not pin the libraries inside generated code. See dependency risk in generated clients.
The steps for holding the version are in how to pin the OpenAPI Generator version in CI, and the launcher's behaviour is covered in the bash launcher post.
Where Safeguard fits
Safeguard keeps an inventory of dependencies and build tools declared in your repositories through SBOM and dependency scanning, and continuous monitoring can flag when something in that inventory gains a new advisory. Try the free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how a new advisory is matched against an existing inventory.
Quick check
Does the Docker image avoid needing Java?
Yes. The docs describe it as an option for developers who cannot install Java or upgrade the installed version.
Which route do the docs recommend?
They list them side by side without ranking. Pick by your need for pinning and trust.
Sources
Last reviewed: 19 October 2026.
