Develocity Command Line Tool (develocityctl) User Manual

Installing develocityctl

develocityctl is distributed in two forms:

As an executable JAR file
As a Docker image

Installing the JAR file

Prerequisites

To run the develocityctl JAR, you will need a Java 21 or newer available locally on the machine you wish to use the CLI on.

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

Install the develocityctl binary with curl

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

$ curl -L -o develocityctl.jar https://docs.gradle.com/develocity/admin-cli/develocityctl-jar/develocityctl-1.15.jar

To download a specific version, see Appendix C: Develocityctl JAR downloads for the download links and follow the same steps with replacing the version of develocityctl.

Validate the binary (optional)

Download the develocityctl checksum file:

$ curl -L -o develocityctl-1.15.jar.sha256 https://docs.gradle.com/develocity/admin-cli/develocityctl-jar/develocityctl-1.15.jar.sha256

Validate the develocityctl binary against the checksum file:

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

If valid, the output is:

develocity: OK

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

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

Download the same version of the binary and checksum.

3 Install develocityctl

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

Optional: Create a shell alias

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

Steps to create a shell alias

Set up a shell alias to run the develocityctl JAR file.
- For Bash, save the following alias to your .bashrc or .bash_profile file
- For Zsh, save the following alias to your .zshrc file
- For other shells, save the following alias to the appropriate configuration file
Load the alias into your current shell session by running source ~/.bashrc or source ~/.zshrc (or source the appropriate file for your shell).
Example:
alias develocityctl="java -jar /opt/gradle/develocityctl/develocityctl.jar"
Verify develocityctl works using the alias you created. You should see a list of available commands.
```
develocityctl
```

Installing the develocityctl Docker image

Prerequisites

To run the develocityctl docker image from a Docker container, you will need:

A Docker runtime and CLI tools available
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 in order 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 develocityctl is installed using the function you created. You should see a list of available commands.
```
docker run --rm -it gradle/develocityctl
```

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.9`. `latest` will be used when no tag is provided (as in the example above).

If running on a platform other than linux/amd64 (e.g. an M1 MacBook Pro), you may see the following warning when running develocityctl:

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, it is possible to 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 is 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. Please see the help text for a command by running it with --help to see if this is available for a given command.

Connecting develocityctl 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 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 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 is 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 into the container.

If you used a namespace other than the default, you may need to specify the namespace of the Develocity instance using 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

It is possible to set the default context:

kubectl config use-context my-example-context-name

Specifying the context by name

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

java -jar /opt/gradle/develocityctl/develocityctl.jar --kube-ctx=my-example-context-name

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

develocityctl --kube-ctx=my-example-context-name

Specifying the Kubernetes cluster by URL and token

If running on a machine without a local Kubernetes client configuration set up, it is possible to instead connect to a cluster by providing its URL and an authentication token:

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

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

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

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=my-example-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:

java -jar /opt/gradle/develocityctl/develocityctl.jar --kube-ns=my-example-namespace

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

develocityctl --kube-ns=my-example-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=my-example-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=my-example-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:

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 will be printed to the console. Otherwise, an error message will be displayed.

Available commands

To see a list of available commands, run the tool with no arguments.

backup            Create and restore database backups
backup create     Create a database backup
backup copy       Copy a database backup to a local file
backup restore    Restore the database from a local backup file

build-scan         Work with Build Scan data
build-scan copy    Copy Build Scan data between Develocity installations.

config-file                 Provides tools for authoring a Develocity configuration file
config-file hash            Cryptographically hash a secret for storing in a config file
config-file generate-key    Create a key for symmetric encryption of secrets
config-file encrypt         Encrypt a secret value for storing in a config file
config-file encrypt-all     Encrypt all secrets of a config file
config-file decrypt         Decrypt an encrypted value from a config file
config-file decrypt-all     Decrypt all secrets of a config file
config-file validate        Verify that a config file is well-formed
config-file schema          Prints the JSON schema for Develocity configuration files

database                Execute commands on the Develocity database
database check-index    Check Develocity database indexes for corruption
database query          Execute queries against the Develocity database

license            Print license file details and convert between license file formats
license convert    Reads a Develocity license in any format and writes back out it in a specified format

support-bundle    Create a support bundle for sending to Gradle support

system                                      System command to interact with Develocity
system disable-default-identity-provider    Disable the default identity provider
system get-default-system-password          Get the default Develocity system password
system reset-system-password                Reset Develocity system password
system stop                                 Stop all Develocity components
system start                                Start Develocity components
system restart                              Restart Develocity
system test-notification                    Execute a notification test

beta                           Commands currently in beta stage
beta system                    System command to interact with Develocity
beta system prune-resources    Prunes stale kubernetes object from previous releases

Appendix A: Release history

1.15

8th April 2025

[NEW] Commands system reset-system-password and config-file hash require a password to be at least eight characters long, contain one digit and one special character.
[NEW] support-bundle command can create support bundles for Develocity Reporting Kit installations.

1.14

18th February 2025

[NEW] The support bundle generation process now skips exporting proxy access logs by default. This change reduces the size of the support bundle and improves its performance.
[FIX] Support Bundle metrics generation may fail for large installations. This change addresses the issue by streaming the metrics.zip files in a memory-efficient way.
[FIX] The support-bundle command doesn’t use command line parameters when generating a bundle on the server side.

1.13

12th December 2024

[NEW] The support bundle generation process has been unified to use the exact mechanism when triggered via develocityctl or Develocity UI; this change improves performance and predictability.

1.12

19th August 2024

[NEW] Update Alpine version to 3.20.2 in base image

1.11

22nd May 2024

[NEW] Support-bundle contains version metadata
[FIX] The develocityctl system start command ignores number of replicas

1.10

2nd April 2024

[FIX] develocityctl fails to run on Windows hosts
[NEW] develocityctl requires Java 21+ runtime when used as a JAR
[NEW] Update JDK Docker base image to JDK 21.0.1-16

1.9

5th December 2023

Renamed to develocityctl from Admin CLI
Require Java 17+ runtime when used as a JAR
Update JDK Docker base image to JDK 17.0.9-11
Adds flags to control the date range of logs captured in the support bundle
New command to copy Build Scan data between instances of Develocity
When generating a support bundle, Develocity prioritizes collecting other logs before proxy access logs
Command "support-bundle" now prints progress messages to the console

1.8.1

27th October 2023

Adds a flag to configure maximum time spent on gathering logs into a support bundle
Fix Admin CLI 1.8 fails to find database type in installations older than 2023.3
Fix typo in path when generating a support bundle

1.8

13th September 2023

Improvements to support bundle generation

1.7.3

18th July 2023

Update Alpine version to 3.18.0 in base image

1.7.2

09th May 2023

Update JDK Docker base image to JDK 11.0.19

1.7.1

18th April 2023

Fix Out of memory error when generating a support bundle

1.7

12th April 2023

Add system get-default-system-password command to get the default system password

1.6.3

20th February 2023

Fix database query errors not being reported

1.6.2

30th January 2023

Admin CLI attempts to find a Develocity installation if no namespace is provided
Admin CLI reports back if it can’t detect a GE instance when generating a support bundle
Update JDK Docker base image to JDK 11.0.18

1.6.1

20th December 2022

Malformed license data does not prevent support bundle generation

1.6

8th December 2022

Capture additional diagnostics in support bundles
Improve error handling when generating support bundles
Improve error reporting on backup upload failures

1.5.1

11th November 2022

Fix backup restore command file transfer issue in 1.5

1.5

8th November 2022

Add a system restart command to restart a Develocity deployment in one command.
Improve the speed of embedded database backup transfers
Update JDK Docker base image to JDK 11.0.17

1.4

10th August 2022

The database query command fails if not exactly one of the --query and --query-file options are passed to it.
If a custom shared database schema is configured, the database query command will use it when determining the search path for running queries.
The --no-output-file option doesn’t cause a non-zero exit code when used from the Docker image.
Backup commands fail fast when run against a user-managed database. When Develocity is configured to connect to a user-managed database, administrators should consult their database service provider or database administrator to configure backups.
Admin CLI creates intermediate directories with the correct ownership.
backup copy prints the local path on the installation host where backups are saved, when running in standalone-mode.
Update JDK Docker base image to JDK 11.0.16

1.3.1

19th May 2022

Mitigate RCE related to CVE-2022-30586
Update JDK Docker base image to JDK 11.0.15 to mitigate ECDSA vulnerability

1.3

19th April 2022

Remove get-installation-key command

1.2.1

25th March 2022

Handle file permissions correctly when run in a docker container
Treat absolute paths correctly during support bundle generation

1.2

3rd March 2022

Support for the Develocity Helm-based deployment platform, including the system, backup, support-bundle, license and database top-level commands

1.1

15th March 2021

Support for generating and validating the Develocity 2021.1 configuration model

1.0

28th October 2020

Support for generating and validating the Develocity 2020.4 configuration model via the config-file command