Skip to main content

Reference

Comprehensive reference for javm commands, flags, selectors, and configuration.

Global CLI​

  • Command: javm
  • Global flags:
    • --version: print javm version and exit.
    • --debug: enable verbose debug logging.
    • --quiet: suppress non‑error logs.

Commands​

install​

  • Usage: javm install [selector]
  • Description: Download and install a JDK. If no selector is provided, reads .java-version from the current directory.
  • Selector forms:
    • Distribution + version/range: temurin@21, zulu@~1.8.144
    • Custom URL: <version>=<url> (e.g. 1.8.0-custom=https://example.com/dist.tar.gz)
  • Flags:
    • -o, --output <path>: install to custom destination. Managed installs go to <cfg.Dir()>/jdk/<version>.
  • Behavior:
    • If the version is already installed, it is reused.
    • On managed installs, link targets are refreshed to track the latest minor (via LinkLatest).

uninstall​

  • Usage: javm uninstall [selector]
  • Description: Uninstall a managed JDK that matches the selector.
  • Notes:
    • system@... links cannot be uninstalled; use javm unlink system@... instead.
  • Usage:
    • javm link → refresh latest minor symlinks.
    • javm link [name] → show link target for name.
    • javm link [name] [path] → create/update link.
  • Description: Manage symlinks in <cfg.Dir()>/jdk to point names like system@1.8.72 or 1.8 to actual JDK directories.
  • Constraints:
    • Names for system JDKs must begin with system@ and be valid semver selectors.
  • Usage: javm unlink [name]
  • Description: Remove a link from <cfg.Dir()>/jdk.

use​

  • Usage: javm use [selector]
  • Description: Modify current shell PATH and JAVA_HOME to use a specific JDK.
  • Behavior:
    • Without arguments, reads .java-version from current directory.
    • Strips any previous javm/Jabba jdk references from PATH before setting the new one.
    • On macOS, uses <path>/Contents/Home for JAVA_HOME.

current​

  • Usage: javm current
  • Description: Print the currently active javm version (if java resolves under <cfg.Dir()>/jdk).

ls​

  • Usage: javm ls [range] [--latest=major|minor|patch]
  • Description: List installed versions, optionally filtered by range.
  • Flags:
    • --latest: trim list to latest per major/minor/patch.

ls-remote​

  • Usage: javm ls-remote [range] [flags]
  • Description: List remote versions available for install.
  • Flags:
    • --os: target OS (macos, linux, windows), defaults to current.
    • --arch: target arch (amd64, arm64), defaults to current.
    • --distribution: Java distribution (e.g. temurin, zulu, corretto). Use all to list all.
    • --latest: trim list to latest per major/minor/patch.
  • Output: shows Identifier (trimmed version), Full Version, Distribution and Distribution Version.

ls-distributions​

  • Usage: javm ls-distributions
  • Description: List all available distributions from DiscoAPI.
  • Output columns: Identifier and Name.

which​

  • Usage: javm which [selector] [--home]
  • Description: Print path to the installed JDK that matches selector; without selector, uses .java-version.
  • Flags:
    • --home: append /Contents/Home on macOS so result is suitable for JAVA_HOME.

init​

  • Usage: javm init [shell]
  • Description: Print shell integration script for javm (bash, zsh, fish, nushell, pwsh/powershell).
  • Behavior:
    • Replaces ::JAVM:: placeholder with path to the current executable.
    • If default-version exists in config dir, appends javm use <version> to init script.
    • On PowerShell, writes a temp script file and prints a command to execute it.

discover​

  • Parent: javm discover
  • Subcommands:
    • refresh: force refresh of local discovery cache (TTL=0).
    • list: list discovered JDKs. Use -d, --details for full columns.
  • Sources used: system, jabba, gradle, IntelliJ, javm.

default​

  • Usage: javm default [selector]
  • Description: Set default Java version for new shells. Writes to default-version in config dir.

Selectors and ranges​

  • Qualifier + version/range: temurin@21, zulu@~1.8.144, * @ >=1.6.45 <1.9 (use all with ls-remote instead of *).
  • Range syntax (powered by Masterminds semver with compatibility tweaks):
    • 1.8, 1.8.x (implicit .x for partial forms), ~21.0.2, >=21 <22.
    • Pre‑0.7 compatibility adds .x to single/double‑component ranges and inserts separators where needed.
  • Trimming:
    • --latest=major|minor|patch returns only the latest version per group.

Configuration​

  • Config directory (cfg.Dir()):
    • Override with JAVM_HOME.
    • Defaults:
      • Windows: %LOCALAPPDATA%\javm
      • macOS: ~/Library/Application Support/javm
      • Linux/Unix: $XDG_DATA_HOME/javm or ~/.local/share/javm
  • Managed installs live under <cfg.Dir()>/jdk/<version>.
  • Aliases: stored as <cfg.Dir()>/<name>.alias; link alias maintains <cfg.Dir()>/jdk/<name> symlink.
  • .java-version: read from current working directory for use, install, which when selector is omitted.
  • Default version: <cfg.Dir()>/default-version (used by javm init to auto‑use on new shells).
  • Discovery cache: <cfg.Dir()>/cache.json with default TTL of 24h.
  • Discovery config: <cfg.Dir()>/autodiscover/config.json (contains enabled, per‑source toggles, and cache_ttl).

Logging​

  • --debug: verbose logs.
  • --quiet: warning and errors only.