Installation and Configuration

Installing develocityctl

develocityctl is distributed in two forms:

As an executable JAR file
As a Docker image

Installing the JAR File

develocityctl is distributed as an executable JAR that runs on any host with a compatible Java runtime.

Prerequisites

The develocityctl JAR requires Java 21 or later on the host machine.

For standalone installations, develocityctl must be installed on the Develocity host to interact with the Develocity instance (for example, the support-bundle and system restart commands).

Install the Binary With Curl

Download the latest release and save it as develocityctl.jar:

curl -L -o develocityctl.jar https://docs.develocity.ai/downloads/develocityctl/develocityctl-1.23.0.jar

Validate the binary (optional)

Download the checksum file:

curl -L -o develocityctl-1.23.0.jar.sha256 https://docs.develocity.ai/downloads/develocityctl/develocityctl-1.23.0.jar.sha256

Validate the binary against the checksum file:

echo "$(cat develocityctl-1.23.0.jar.sha256)  develocityctl.jar" | sha256sum --check

If valid, the output is:

Output

develocityctl.jar: OK

If the check fails, sha256 exits with nonzero status and prints output similar to:

Output

develocityctl.jar: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match

Download the same version of the binary and checksum.

Install develocityctl:

sudo mv develocityctl.jar /opt/gradle/develocityctl/develocityctl.jar

Create a Shell Alias

You can create a shell alias to make it easier to invoke develocityctl.

Define the shell alias:
- For Bash, save the following alias to your .bashrc or .bash_profile file
- For Zsh, save the following alias to your .zshrc file
  Example:
  alias develocityctl="java -jar /opt/gradle/develocityctl/develocityctl.jar"
Activate the alias in your current shell:

Load the alias into your current shell session by running the appropriate command:
- Bash
- Zsh
source ~/.bashrc
source ~/.zshrc

Verify the alias:

Verify that the develocityctl alias is working correctly. You should see a list of available commands:

develocityctl

Output

Usage: develocityctl [-v] COMMAND

A utility for administering Develocity installations

Options:
  -v, --version   Print version information and exit.

Commands:
  backup          Create and restore database backups
  config-file     Provides tools for authoring a Develocity configuration file
  build-scan      Work with Build Scan data
  database        Execute commands on the Develocity database
  license         Print license file details and convert between license file formats
  support-bundle  Create a support bundle for sending to Gradle support
  system          System command to interact with Develocity

Run 'develocityctl COMMAND --help' for more information on a command.

Installing the Docker Image

develocityctl is also available as a Docker image, which avoids the need for a local Java installation.

Prerequisites

Running the develocityctl Docker image requires:

A Docker runtime and CLI tools
A machine with access to pull the gradle/develocityctl image from Docker Hub, or to have pulled it into an accessible registry

For standalone installations, develocityctl must be installed on the Develocity host to interact with the Develocity instance (use commands like the support-bundle and system restart commands).

Installation Steps

Pull the Docker image from Docker Hub:
```
docker pull gradle/develocityctl
```

Verify the installation by running the image directly:

docker run --rm -it gradle/develocityctl

Output

Usage: develocityctl [-v] COMMAND

A utility for administering Develocity installations

Options:
  -v, --version   Print version information and exit.

Commands:
  backup          Create and restore database backups
  config-file     Provides tools for authoring a Develocity configuration file
  build-scan      Work with Build Scan data
  database        Execute commands on the Develocity database
  license         Print license file details and convert between license file formats
  support-bundle  Create a support bundle for sending to Gradle support
  system          System command to interact with Develocity

Run 'develocityctl COMMAND --help' for more information on a command.

Optional: Create a Shell Function

You can create a shell function to make it easier to invoke develocityctl.

Steps to Create a Shell Function

Set up a shell function to run the develocityctl Docker image.

For Bash, save the following function to your .bashrc or .bash_profile file
For Zsh, save the following function to your .zshrc file

For other shells, save the following function to the appropriate configuration file

Example:

function develocityctl() {
  docker run --rm -it \
    -v "${HOME}/.kube/config:/kube-config:ro" \(1)
    -v "${PWD}:/home" \(2)
    gradle/develocityctl \(3)
    "$@"
}

1	This makes your local Kubernetes client configuration available to the Docker container. Adjust this if the config is stored in a different location.
2	Mount the current directory into the Docker container. See Working With Files When Using the Docker Image.
3	A specific version of the tool can be selected by appending a tag. E.g. `gradle/develocityctl:1.23.0`. `latest` will be used when no tag is provided (as in the example above).

If running on a platform other than linux/amd64 (for example a Mac with Apple silicon), you may see the following warning when running develocityctl:

Output

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

You can safely ignore the warning, or you can suppress the warning by adding --platform linux/amd64 to the docker run command in the shell function.

Load the function into your current shell session by running source ~/.bashrc or source ~/.zshrc (or source the appropriate file for your shell).
Invoke the shell function to verify it works. You should see a list of available commands.
```
develocityctl
```

Working With Files When Using the Docker Image

A Docker container by default cannot access your local filesystem. Instead, mount a local directory to a path inside the container as a volume.

Some commands need to read or write files from the local filesystem. It’s necessary to mount files or directories into the container in these cases.

The tool executes in the /home directory inside the container. Thus, mounting a directory to /home makes files in that directory available to the tool, and it will write files inside that directory by default.

Mounting a directory is achieved by adding a -v host-path:container-path option to the Docker command.

The optional shell function mounts the current directory to the home directory inside the container. This works well for most commands. For some commands, you might need to mount a different directory or file. In these cases, you may need to edit the function, or invoke Docker directly.

Here is an example of how to run the support-bundle command and save the support bundle to a directory called bundles in your home directory:

docker run --rm -it \
  -v "${HOME}/.kube/config:/kube-config:ro" \
  -v "${HOME}/bundles:/home" \(1)
  gradle/develocityctl \
  --kube-ns=develocity \
  support-bundle

1	Mounts the `${HOME}/bundles` directory to the `/home` directory inside the container. Use `-v "${PWD}:/home"` instead if you want to save the support bundle to the current working directory.

Many commands have options to accept input from standard input or to produce their output to standard output. See the help text for a command by running it with --help to see if this is available for a given command.

Connecting to Your Develocity Instance

Connecting to a Standalone Develocity Instance

If you are running develocityctl using the JAR file, it will automatically detect the Standalone Develocity instance running on the same host by looking at the default Kubernetes configuration file (~/.kube/config).

If you are running develocityctl using the Docker image, then you need to mount the default Kubernetes configuration file at /kube-config inside the container.

docker run --rm -it \
  -v "${HOME}/.kube/config:/kube-config:ro" \(1)
  gradle/develocityctl \
  system get-default-system-password

1	Example of mounting the default Kubernetes configuration file into the correct location inside the container. Adjust this if the config is stored in a different location.

Providing the default Kubernetes configuration is all that’s needed for develocityctl to connect to the Standalone Develocity instance.

The optional shell function for running develocityctl with Docker already mounts the default Kubernetes configuration file. If you used a non-default namespace, specify it with the --kube-ns option.

Connecting to a Kubernetes Develocity Instance

To connect to the Kubernetes cluster into which Develocity has been installed, the tool needs to discover or be provided with connection details.

Using the Default Context From the Environment

Kubernetes client configuration is usually stored in the ${HOME}/.kube/config file. If a default context is configured there, the tool will detect this and attempt to connect to that cluster.

To check which contexts are available, and which is the default, run this command:

kubectl config get-contexts

Set the default context:

kubectl config use-context CONTEXT_NAME

Specifying the Context by Name

If there is no default set, or if you want to select the context to use without altering the local environment, it can be specified as an option:

JAR
Docker
Alias

java -jar /opt/gradle/develocityctl/develocityctl.jar --kube-ctx=CONTEXT_NAME

docker run -it --rm \
  -v "${HOME}/.kube/config:/kube-config:ro" \
  -v "${PWD}:/home" \
  gradle/develocityctl \
  --kube-ctx=CONTEXT_NAME

develocityctl --kube-ctx=CONTEXT_NAME

Specifying the Kubernetes Cluster by URL and Token

If running on a machine without a local Kubernetes client configuration, connect to the cluster by providing its URL and an authentication token:

JAR
Docker
Alias

java -jar /opt/gradle/develocityctl/develocityctl.jar \
  --kube-url=https://kube.example.com:1234 --kube-token=API_TOKEN

docker run -it --rm \
  -v "${PWD}:/home" \
  gradle/develocityctl \
  --kube-url=https://kube.example.com:1234 --kube-token=API_TOKEN

develocityctl --kube-url=https://kube.example.com:1234 --kube-token=API_TOKEN

Specifying the Namespace

If using a locally configured context, a default namespace may be configured. If so, the tool will look for a Develocity instance in that namespace.

To check if your current context has a default namespace set, run this command:

kubectl config view -o jsonpath='{..namespace}'

The namespace can be set as the default for the current context by running this command:

kubectl config set-context --current --namespace=NAMESPACE

If there is no current context, or if there is but there is no default namespace, or if Develocity is on a different namespace to the default, you can specify the namespace to use as an argument to the tool:

JAR
Docker
Alias

java -jar /opt/gradle/develocityctl/develocityctl.jar --kube-ns=NAMESPACE

docker run -it --rm \
  -v "${HOME}/.kube/config:/kube-config:ro" \
  -v "${PWD}:/home" \
  gradle/develocityctl \
  --kube-ns=NAMESPACE

develocityctl --kube-ns=NAMESPACE

Updating the JAR File Shell Alias

If you created an alias for develocityctl, then you can update the alias to include the connection flags. For example, to connect to a Develocity instance in the develocity namespace, you can update the alias to include the --kube-ns flag:

alias develocityctl="java -jar /opt/gradle/develocityctl/develocityctl.jar --kube-ns=NAMESPACE"

Updating the Docker Image Shell Function

If you created a shell function for develocityctl, then you can update the shell function to include the connection flags. For example, to connect to a Develocity instance in the develocity namespace, you can update the function to include the --kube-ns flag:

function develocityctl() {
  docker run --rm -it \
    --platform linux/amd64 \
    -v "${HOME}/.kube/config:/kube-config:ro" \
    -v "${PWD}:/home" \
    gradle/develocityctl \
    --kube-ns=NAMESPACE \(1)
    "$@"
}

1	Add the `--kube-ns` flag to specify the namespace.

Verifying the Connection

To verify develocityctl can connect to the Develocity instance, run the system get-default-system-password command:

JAR
Docker
Alias

java -jar /opt/gradle/develocityctl/develocityctl.jar system get-default-system-password

docker run -it --rm \
  -v "${HOME}/.kube/config:/kube-config:ro" \
  -v "${PWD}:/home" \
  gradle/develocityctl \
  system get-default-system-password

develocityctl system get-default-system-password

If the connection is successful, the default system password is printed to the console. If the connection fails, an error message is displayed.

Appendix A: JAR Download Links

The develocityctl JAR file and verification files for version 1.23.0 are available at the following links:

Appendix B: Verifying the Signature of the JAR

The develocityctl JAR is published alongside its signature. The public key is published to https://keyserver.ubuntu.com. You can verify the signature as follows:

curl -OL https://docs.develocity.ai/downloads/develocityctl/develocityctl-1.23.0.jar && \
  curl -OL https://docs.develocity.ai/downloads/develocityctl/develocityctl-1.23.0.jar.asc && \
  gpg --keyserver keyserver.ubuntu.com --recv-key 7B79ADD11F8A779FE90FD3D0893A028475557671 && \
  gpg --verify develocityctl-1.23.0.jar.asc develocityctl-1.23.0.jar

The output of the last command should look similar to the following:

Output

gpg: Signature made Tue Jun 30 12:33:04 2026 UTC
gpg:                using RSA key 893A028475557671
gpg: Good signature from "Gradle Inc. <[email protected]>" [unknown]
gpg: WARNING: This key has been revoked by its owner!
gpg:          This could mean that the signature is forged.
gpg: reason for revocation: Key is superseded
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7B79 ADD1 1F8A 779F E90F  D3D0 893A 0284 7555 7671

This verifies that the artifact was signed with the private key that corresponds to the imported public key. The warning is emitted because you haven’t explicitly trusted the imported key (therefore [unknown]). One way of establishing trust is to verify the fingerprint over a secure channel. Please contact Develocity support should you want to do so.

This key was superseded by a new Develocity signing key, so gpg reports it as revoked. The signature is still valid: the revocation reason is Key is superseded, which leaves signatures made with the key intact. Fetch the key from keyserver.ubuntu.com as shown above. keys.openpgp.org no longer serves the user IDs of this key, and gpg refuses to import a key that carries none.

Previous Releases

For information about previous develocityctl releases, see the release history.