The Develocity Admin CLI tool is a command line program that can perform tasks related to your Develocity instance. Some of these tasks require it to connect to your instance.
Installing the Admin CLI
The Develocity Admin CLI is distributed in two forms:
-
As an executable JAR file
-
As a Docker image
Installing the Admin CLI JAR file
Prerequisites
To run the Admin CLI JAR, you will need a Java 21 or newer runtime available locally on the machine you wish to use the Admin CLI on.
For standalone installations, the Admin CLI must be installed on the Develocity host in order to interact with the Develocity instance (for example, the support-bundle and system restart commands). |
Installation steps
-
Download the Admin CLI JAR file.
-
See Appendix C: Develocityctl JAR downloads for the download links.
-
-
Save the Admin CLI JAR file to a location where you can easily access it. Recommended location:
/opt/gradle/develocityctl/develocityctl.jar
-
Verify the Admin CLI works by invoking the jar. You should see a list of available commands.
java -jar /opt/gradle/develocityctl/develocityctl.jar
Optional: Create a shell alias
You can create a shell alias to make it easier to invoke the Admin CLI.
Steps to create a shell alias
-
Set up a shell alias to run the Admin CLI 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
orsource ~/.zshrc
(or source the appropriate file for your shell).Example:
alias develocityctl="java -jar /opt/gradle/develocityctl/develocityctl.jar"
-
Verify the Admin CLI works using the alias you created. You should see a list of available commands.
develocityctl
Installing the Admin CLI Docker image
Prerequisites
To run the Admin CLI 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, the Admin CLI 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 Admin CLI Docker image from Docker Hub:
docker pull gradle/develocityctl
-
Verify the Admin CLI 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 the Admin CLI.
Steps to create a shell function
-
Set up a shell function to run the Admin CLI 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 the Admin CLI with Docker:
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 thedocker run
command in the shell function.
-
-
Load the function into your current shell session by running
source ~/.bashrc
orsource ~/.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 the Admin CLI to your Develocity instance
Connecting to a Standalone Develocity instance
If you are running the Admin CLI using the JAR file, the Admin CLI 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 the Admin CLI 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 in order for the Admin CLI to connect to the Standalone Develocity instance.
The optional shell function for running the Admin CLI 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 speficied 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 namesace 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 the Admin CLI, 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 the Admin CLI, 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 the Admin CLI 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.12
-
[NEW] Update Alpine version to 3.20.2 in base image
1.11
-
[NEW] Support-bundle contains version metadata
-
[FIX] DevelocityCtl cluster start command ignores number of replicas
1.10
-
[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
-
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
-
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
-
Improvements to support bundle generation
1.7.3
-
Update Alpine version to 3.18.0 in base image
1.7.2
-
Update JDK Docker base image to JDK 11.0.19
1.7.1
-
Fix Out of memory error when generating a support bundle
1.7
-
Add
system get-default-system-password
command to get the default system password
1.6.3
-
Fix database query errors not being reported
1.6.2
-
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
-
Malformed license data does not prevent support bundle generation
1.6
-
Capture additional diagnostics in support bundles
-
Improve error handling when generating support bundles
-
Improve error reporting on backup upload failures
1.5.1
-
Fix
backup restore
command file transfer issue in 1.5
1.5
-
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
-
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
-
Mitigate RCE related to CVE-2022-30586
-
Update JDK Docker base image to JDK 11.0.15 to mitigate ECDSA vulnerability
1.3
-
Remove
get-installation-key
command
1.2.1
-
Handle file permissions correctly when run in a docker container
-
Treat absolute paths correctly during support bundle generation
1.2
-
Support for the Develocity Helm-based deployment platform, including the
system
,backup
,support-bundle
,license
anddatabase
top-level commands
1.1
-
Support for generating and validating the Develocity 2021.1 configuration model
1.0
-
Support for generating and validating the Develocity 2020.4 configuration model via the
config-file
command
Appendix B: Compatibility with Develocity
Compatibility between versions of Develocity and the Develocity Admin CLI can be found in the compatibility document.
Appendix C: Develocityctl JAR downloads
-
develocityctl-1.13.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
develocityctl-1.12.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
develocityctl-1.11.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
develocityctl-1.10.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
develocityctl-1.9.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
Appendix D: (Legacy) Develocity Admin CLI JAR downloads
-
gradle-enterprise-admin-1.8.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.8.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.7.3.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.7.2.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.7.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.7.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.6.3.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.6.2.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.6.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.6.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.5.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.5.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.4.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.3.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.3.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.2.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.2.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.0.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)