Command line interface

Command line interface#

Common options#

The cjdk command-line interface is organized into subcommands. A list of available subcommands and common options can be displayed using the --help option.

$ cjdk --help
Usage: cjdk [OPTIONS] COMMAND [ARGS]...

  Download, cache, and run JDK or JRE distributions.

  Use 'cjdk COMMAND --help' to see usage of each command. The common options
  shown here must be given before COMMAND.

Options:
  -j, --jdk VENDOR:VERSION    Specify JDK vendor and version.
  --cache-dir DIR             Override root cache directory.
  --index-url URL             Use alternative JDK index URL.
  --index-ttl SECONDS         Time to live for cached JDK index.
  --os NAME                   Operating system for JDK.
  --arch NAME                 Architecture for JDK.
  --progress / --no-progress  Show or do not show progress bars.
  --version                   Show the version and exit.
  --help                      Show this message and exit.

Commands:
  cache          Ensure the requested JDK is cached.
  cache-file     Cache an arbitrary file.
  cache-package  Cache an arbitrary package.
  exec           Run a program using the requested JDK.
  java-home      Print the Java home directory for the requested JDK.
  ls             List cached or available JDKs matching criteria.
  ls-vendors     List available JDK vendors.

Added in version 0.2.0: --index-url, --index-ttl, --os, and --arch

More details about the choices and defaults for VENDOR, VERSION, and --cache_dir are available on separate pages.

Querying the JDK index#

ls#

$ cjdk ls --help
Usage: cjdk ls [OPTIONS]

  Print the list of JDKs matching the given criteria.

  See 'cjdk --help' for the common options used to specify the criteria.

Options:
  --cached / --available  Show only already-cached JDKs, or show all available
                          JDKs from the index (default cached only).
  --help                  Show this message and exit.

Added in version 0.4.0.

ls-vendors#

$ cjdk ls-vendors --help
Usage: cjdk ls-vendors [OPTIONS]

  Print the list of available JDK vendors.

Options:
  --help  Show this message and exit.

Added in version 0.4.0.

Working with cached JDKs#

exec#

$ cjdk exec --help
Usage: cjdk exec [OPTIONS] PROG [ARGS]...

  Run PROG with the environment variables set for the requested JDK.

  The JDK is downloaded if not already cached.

  See 'cjdk --help' for the common options used to specify the JDK and how it
  is obtained.

  Pass '--' before PROG to prevent any of ARGS to be interpreted by cjdk.

Options:
  --help  Show this message and exit.

For example, run the java command from the Temurin JRE 17.0.3 with the -version option, installing the JRE if necessary:

$ cjdk --jdk temurin-jre:17.0.3 exec -- java -version
cjdk: Installing JDK temurin-jre:1.17.0.3 to /home/runner/.cache/cjdk
openjdk version "17.0.3" 2022-04-19
OpenJDK Runtime Environment Temurin-17.0.3+7 (build 17.0.3+7)
OpenJDK 64-Bit Server VM Temurin-17.0.3+7 (build 17.0.3+7, mixed mode, sharing)

java-home#

$ cjdk java-home --help
Usage: cjdk java-home [OPTIONS]

  Print the path that is suitable as the value of JAVA_HOME for the requested
  JDK.

  The JDK is downloaded if not already cached.

  See 'cjdk --help' for the common options used to specify the JDK and how it
  is obtained.

Options:
  --help  Show this message and exit.

For example, to print the Java home directory for the Temurin JRE 17.0.3, installing it if necessary:

$ cjdk --jdk temurin-jre:17.0.3 java-home
/Users/mark/Library/Caches/cjdk/v0/jdks/0f77e52f812d326e1137d7a22b81d6c328679c68/jdk-17.0.3+7-jre/Contents/Home

(The output will depend on your operating system and configuration; the example shown was on macOS.)

cache#

$ cjdk cache --help
Usage: cjdk cache [OPTIONS]

  Download and extract the requested JDK if it is not already cached.

  Usually there is no need to invoke this command on its own, but it may be
  useful if you want any potential JDK download to happen at a controlled
  point in time.

  See 'cjdk --help' for the common options used to specify the JDK and how it
  is obtained.

Options:
  --help  Show this message and exit.

Changed in version 0.4.0: Renamed from cache-jdk.

Caching arbitrary files and packages#

cache-file#

$ cjdk cache-file --help
Usage: cjdk cache-file [OPTIONS] URL FILENAME

  Download and store an arbitrary file if it is not already cached.

  The file at URL (whose scheme must be https) is stored in the cache with the
  given FILENAME, and the full path to it is printed to standard output.

  See 'cjdk --help' for the common options (JDK-specific options are ignored).

Options:
  --name NAME    Name to display in progress message.
  --ttl SECONDS  Time to live for the cached file.
  --sha1 HASH    Check the downloaded file against the given SHA-1 hash.
  --sha256 HASH  Check the downloaded file against the given SHA-256 hash.
  --sha512 HASH  Check the downloaded file against the given SHA-512 hash.
  --help         Show this message and exit.

Added in version 0.2.0.

cache-package#

$ cjdk cache-package --help
Usage: cjdk cache-package [OPTIONS] URL

  Download, extract, and store an arbitrary .zip or .tar.gz package if it is
  not already cached.

  The file at URL (whose scheme must be tgz+https or zip+https) is extracted
  into a directory in the cache, and the full path to the directory is printed
  to standard output.

  See 'cjdk --help' for the common options (JDK-specific options are ignored).

Options:
  --name NAME    Name to display in progress message.
  --sha1 HASH    Check the downloaded file against the given SHA-1 hash.
  --sha256 HASH  Check the downloaded file against the given SHA-256 hash.
  --sha512 HASH  Check the downloaded file against the given SHA-512 hash.
  --help         Show this message and exit.

Added in version 0.2.0.

Contents