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
  • 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 a link.
  • Description: Register an existing JDK under a system@... link in <cfg.Dir()>/jdk.
  • Constraints:
    • The name must begin with system@ and use an exact semantic version, such as system@21.0.1; ranges are not accepted when creating the link.
    • The path must be the root of the expected JDK layout and contain a regular Java executable at:
      • Linux: <path>/bin/java
      • macOS: <path>/Contents/Home/bin/java (pass the bundle root as <path>)
      • Windows: <path>/bin/java.exe
    • link records an existing JDK path; it does not copy or install the JDK.
    • Linked entries are included in javm's local discovery, so ls --details, use, and which can list and resolve the registered system@... name.
  • Examples:
    • javm link system@21.0.1 /path/to/jdk
    • javm use system@21
  • Troubleshooting: if link reports that the Java executable was not found, check that <path> is the JDK root for the current operating system and that the executable path above exists. On macOS, do not pass the nested Contents/Home directory as <path>.
  • To replace an existing link, run javm unlink <name> first and then create it again.
  • Usage: javm unlink <name>
  • Description: Remove a link from <cfg.Dir()>/jdk.

alias​

  • Usage: javm alias <name> [selector]
  • Description: Resolve an alias, or create/update it when a selector is provided.
  • Behavior:
    • With only a name, prints the selector currently bound to the alias.
    • With a name and selector, records the alias and refreshes its local reference to the best matching JDK.
    • use and which resolve an alias name before selecting a JDK.
  • Examples:
    • javm alias project temurin@21
    • javm alias project

unalias​

  • Usage: javm unalias <name>
  • Description: Delete an alias and its local reference.

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.
    • Removes previous javm-managed entries under <cfg.Dir()>/jdk from PATH before setting the new one; external entries, including Jabba entries, are left unchanged.
    • On macOS, uses <path>/Contents/Home for JAVA_HOME.

exec​

  • Usage: javm exec [--jdk <selector>] <command> [args...]
  • Description: Resolve a JDK and execute a process with JAVA_HOME set to that JDK and its bin directory first in PATH. The child inherits the current working directory, stdin, stdout, stderr, and the rest of the environment.
  • Behavior:
    • --jdk <selector> selects an explicit JDK. Without --jdk, exec reads .java-version from the current directory, like use and which.
    • The first argument after the optional --jdk <selector> is the child command. The command and every following argument are passed directly to the child and are not parsed as javm flags. Native executables run without a shell; on Windows, .cmd and .bat wrappers necessarily run through COMSPEC with Windows command-line quoting.
    • Only the child process receives the modified JAVA_HOME and PATH; the current shell is unchanged and javm init is not required.
  • Examples:
    • javm exec java --version
    • javm exec ./gradlew test
    • javm exec mvn -Pproduction package
    • javm exec --jdk 21 java --version
    • javm exec --jdk temurin@21 mvn test

deactivate​

  • Usage: javm deactivate
  • Description: Undo javm's JDK activation in the current shell session.
  • Behavior:
    • Removes javm-managed entries under <cfg.Dir()>/jdk from PATH; other entries are preserved.
    • Restores the previous JAVA_HOME value when one was captured before activation.

current​

  • Usage: javm current
  • Description: Print the active JDK identifier when java resolves under <cfg.Dir()>/jdk; otherwise, print nothing.

ls​

  • Usage: javm ls [range] [-d]
  • Description: List locally discovered JDKs, optionally filtered by range.
  • Flags:
    • -d, --details: show source, name, vendor, architecture, and path.

javm ls uses local discovery and includes JDKs returned by its configured discovery sources, including registered system@... links. To force a fresh scan, use javm discover refresh.

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. Defaults to the effective java.default_distribution configuration value, initially temurin.
    • --latest: trim list to the latest version per major, minor, or patch group. Defaults to major.
  • Output columns: Identifier (trimmed version), Full Version, and Distribution Version. The final column contains the distribution identifier followed by its distribution version, for example temurin 21.0.1.

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 discovered 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 (nu), CMD, and PowerShell (pwsh/powershell)).
  • Behavior:
    • Replaces ::JAVM:: placeholder with path to the current executable.
    • If default-version exists in config dir, initializes the configured default in new shells.
    • On PowerShell, writes a temp script file and prints a command to execute it.
    • On CMD, generates a persistent javm.cmd wrapper that must live in a directory separate from javm.exe.

discover​

  • Parent: javm discover
  • Subcommands:
    • refresh: force a fresh local discovery by bypassing the current cache; it does not change the configured cache TTL.
  • 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.

config​

  • Usage:
    • javm config list
    • javm config get <key>
    • javm config set <key> <value>
    • javm config unset <key>
  • Public key:
    • java.default_distribution: distribution used when an install selector or ls-remote request does not specify one. The initial default is temurin.
  • Examples:
    • javm config get java.default_distribution
    • javm config set java.default_distribution zulu
    • javm config unset java.default_distribution (restore the initial default)
  • An explicit distribution, such as zulu@21 or --distribution temurin, takes precedence over this setting.
  • This is the main javm configuration for remote package selection; it does not configure local JDK discovery.

Selectors and ranges​

  • Qualifier + version/range: temurin@21, zulu@~1.8.144, *@>=1.6.45 <1.9 (use all with ls-remote instead of a wildcard qualifier).
  • 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.
  • Remote-list trimming:
    • --latest accepts major, minor, or patch and returns only the latest version per group. The default is major.

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: create or update them with javm alias <name> <selector>; use and which accept the alias name as a selector.
  • .java-version: read from current working directory for use, install, which, and exec 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.