Commands
This section provides an overview of the commands available in the develocityctl command line tool. Each command is described along with its subcommands and their functionalities.
To view a list of the commands available in your current Develocity version, run develocityctl with no additional arguments:
develocityctlHere is a comprehensive overview of all available commands and their subcommands.
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.
backup
Usage: develocityctl backup COMMAND Create and restore database backups Commands: create Create a database backup copy Copy a database backup to a local file restore Restore the database from a local backup file These commands are only usable when Develocity is using the embedded database. Develocity uses the embedded database by default. If your Develocity installation is configured to connect to a user-managed database, please consult your database service provider or database administrator to configure backups. Run 'develocityctl backup COMMAND --help' for more information on a command.
create
Usage: develocityctl backup create
Create a database backup
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
copy
Usage: develocityctl backup copy [<backup>]
Copy a database backup to a local file
Parameters:
[<backup>] backup file name to be copied
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
JAR Examples:
develocityctl backup copy
restore
Usage: develocityctl backup restore <backup>
Restore the database from a local backup file
Parameters:
<backup> local backup file location
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
JAR Examples:
develocityctl backup restore /somewhere/backup-20220620-111247.zip
config-file
Usage: develocityctl config-file COMMAND Provides tools for authoring a Develocity configuration file Commands: hash Cryptographically hash a secret for storing in a config file generate-key Create a key for symmetric encryption of secrets encrypt Encrypt a secret value for storing in a config file encrypt-all Encrypt all secrets of a config file decrypt Decrypt an encrypted value from a config file decrypt-all Decrypt all secrets of a config file validate Verify that a config file is well-formed schema Prints the JSON schema for Develocity configuration files upgrade Upgrade a config file to a specified or latest schema version Run 'develocityctl config-file COMMAND --help' for more information on a command.
hash
Usage: develocityctl config-file hash [-s=<secret-file>] [-o=<output-file>]
Cryptographically hash a secret for storing in a config file
Hashed values are used for secrets that must be presented to Develocity, such as the system user password.
For secrets that are presented by Develocity, such as the mail server password, see 'encrypt'.
Options:
-s, --secret=<secret-file>
The file containing the secret to hash (use - to read from STDIN)
If omitted, the secret will be prompted for interactively.
-o, --output=<output-file>
The file to write the hashed value to (use - to write to STDOUT)
If omitted, the hashed value will be written to STDOUT.
Supplying the secret inline is not supported to avoid unintentionally leaking it
in the shell history or the process table. You can however simulate this by using STDIN.
Examples:
Reading from secret environment variable
echo "$SECRET" | develocityctl config-file hash -s - -o hashed-secret.txt
Using an inline literal secret
echo "PASSWORD" | develocityctl config-file hash -s - -o hashed-secret.txt
Be mindful that such practices are less secure than using files as it could result
in the key and config being recorded in shell or terminal history.
generate-key
Usage: develocityctl config-file generate-key -o=<output-file>
Create a key for symmetric encryption of secrets
The generated key can be used with the 'encrypt', 'decrypt', 'encrypt-all', 'decrypt-all' commands
to encrypt and decrypt secrets.
The generated key should be treated as a secret itself.
Options:
-o, --output=<output-file>
The file to write the generated key to (use - to write to STDOUT)
As the key can decrypt secrets, take care when writing to STDOUT.
encrypt
Usage: develocityctl config-file encrypt [-k=<key-file>] [-s=<secret-file>] [-o=<output-file>]
Encrypt a secret value for storing in a config file
Encrypted values are used for secrets that must be presented by Develocity, such as the mail server password.
For secrets that are presented to Develocity, such as the system user password, see 'hash'.
Options:
-k, --key=<key-file> The file containing the encryption key (use - to read from STDIN)
The key must be a key generated by the 'generate-key' command.
If omitted, the key will be prompted for interactively.
-s, --secret=<secret-file>
The file containing the secret (use - to read from STDIN)
If omitted, the secret will be prompted for interactively.
-o, --output=<output-file>
The file to write the encrypted secret to (use - to write to STDOUT)
If omitted, the encrypted secret will be written to STDOUT.
When reading both the key and the secret from STDIN, the key is read first terminated by EOL,
then the secret terminated by EOL or EOF.
Supplying the key and/or secret inline is not supported to avoid unintentionally leaking the values
in the shell history or the process table. You can however simulate this by using STDIN.
Examples:
Reading key and secret from environment variables
printf "%s\n%s" "$KEY" "$SECRET" | develocityctl config-file encrypt -k - -s -
Reading key from file and inline secret
echo "PASSWORD" | develocityctl config-file encrypt -k /path/to/key/file -s -
Be mindful that such practices are less secure than using files as it could result
in the key and secret values being recorded in shell or terminal history.
encrypt-all
Usage: develocityctl config-file encrypt-all [-k=<key-file>] -c=<config-file> [-o=<output-file>]
Encrypt all secrets of a config file
If the file is valid and contains no already encrypted secrets the exit code will be 0,
with the config with all secrets encrypted written to <output-file>.
If the file is invalid or has already encrypted secrets the exit code will be 1,
with a description of the problems written to STDERR.
Options:
-k, --key=<key-file> The file containing the encryption key (use - to read from STDIN)
The key must be a key generated by the 'generate-key' command.
If omitted, the key will be prompted for interactively.
-c, --config=<config-file>
The file containing the config (use - to read from STDIN)
-o, --output=<output-file>
The file to write the encrypted config to (use - to write to STDOUT)
If omitted, the config will be written to STDOUT.
When reading both the key and the config from STDIN, the key is read first terminated by EOL,
then the config terminated by EOF.
Supplying the key and config inline is not supported to avoid unintentionally leaking it
in the shell history or the process table. You can however simulate this by using STDIN.
Examples:
Reading key and config from environment variables
printf "%s\n%s" "$KEY" "$CONFIG" | develocityctl config-file encrypt-all \
-k - -c - -o encrypted-config.yaml
Reading key from file and config from environment variable
echo "$CONFIG" | develocityctl config-file encrypt-all \
-k /path/to/key/file -c - -o encrypted-config.yaml
Be mindful that such practices are less secure than using files as it could result
in the key and config being recorded in shell or terminal history.
decrypt
Usage: develocityctl config-file decrypt [-k=<key-file>] [-s=<secret-file>] -o=<output-file>
Decrypt an encrypted value from a config file
The encrypted secret must have been created by the 'encrypt' command.
Encrypted values are used for secrets that must be presented by Develocity, such as the mail server password.
For secrets that are presented to Develocity, such as the system user password, see 'hash'.
Options:
-k, --key=<key-file> The file containing the encryption key (use - to read from STDIN)
The key must be a key generated by the 'generate-key' command.
If omitted, the key will be prompted for interactively.
-s, --secret=<secret-file>
The file containing the secret (use - to read from STDIN)
If omitted, the secret will be prompted for interactively.
-o, --output=<output-file>
The file to write the decrypted secret to (use - to write to STDOUT)
As the output contains decrypted secrets, take care when writing to STDOUT.
When reading both the key and the secret from STDIN, the key is read first terminated by EOL,
then the secret terminated by EOL or EOF.
Supplying the key and/or secret inline is not supported to avoid unintentionally leaking the values
in the shell history or the process table. You can however simulate this by using STDIN.
Examples:
Reading key and secret from environment variables
printf "%s\n%s" "$KEY" "$SECRET" | develocityctl config-file decrypt -k - -s - -o decrypted.txt
Reading key from file and secret from environment variable
echo "$SECRET" | develocityctl config-file decrypt -k /path/to/key/file -s - -o decrypted.txt
Be mindful that such practices are less secure than using files as it could result
in the key and secret values being recorded in shell or terminal history.
decrypt-all
Usage: develocityctl config-file decrypt-all [-k=<key-file>] -c=<config-file> -o=<output-file>
Decrypt all secrets of a config file
If the file is valid and contains no encrypted secrets encrypted with a different key the exit code will be 0,
with the config with all secrets decrypted written to <output-file>.
If the file in invalid or has secrets encrypted with a different key, the exit code will be 1
with a description of the problems written to STDERR.
Options:
-k, --key=<key-file> The file containing the encryption key (use - to read from STDIN)
The key must be a key generated by the 'generate-key' command.
If omitted, the key will be prompted for interactively.
-c, --config=<config-file>
The file containing the config (use - to read from STDIN)
-o, --output=<output-file>
The file to write the encrypted config to (use - to write to STDOUT)
As the output contains decrypted secrets, take care when writing to STDOUT.
When reading both the key and the config from STDIN, the key is read first terminated by EOL,
then the config terminated by EOF.
Supplying the key and config inline is not supported to avoid unintentionally leaking it
in the shell history or the process table. You can however simulate this by using STDIN.
Examples:
Reading key and config from environment variables
printf "%s\n%s" "$KEY" "$CONFIG" | develocityctl config-file decrypt-all \
-k - -c - -o decrypted-config.yaml
Reading key from file and config from environment variable
echo "$CONFIG" | develocityctl config-file decrypt-all \
-k /path/to/key/file -c - -o decrypted-config.yaml
Be mindful that such practices are less secure than using files as it could result
in the key and config being recorded in shell or terminal history.
validate
Usage: develocityctl config-file validate FILE
Verify that a config file is well-formed
If the file is valid, the exit code will be 0 with no logging output.
If the file is invalid, the exit code will be 1 with a description of the problems written to STDERR.
The file may have encrypted or plain text secrets.
To verify that file can be decrypted with a given key, use the 'decrypt-all' command instead of this.
Parameters:
FILE The config file to validate (use - to read from STDIN)
schema
Usage: develocityctl config-file schema Prints the JSON schema for Develocity configuration files
upgrade
Usage: develocityctl config-file upgrade [-o=<output-file>] [--overwrite] [--nested=PATH] [-s=VERSION] FILE
Upgrade a config file to a specified or latest schema version
If the file is already at the target version, it will be written unchanged (preserving formatting and comments).
If the file is upgraded, the exit code will be 0 with the upgraded config written to the output.
WARNING: Comments may be moved or lost if properties are moved, renamed, or removed during the upgrade.
If the file is invalid, the exit code will be 1 with a description of the problems written to STDERR.
Parameters:
FILE The config file to upgrade (use - to read from STDIN)
Options:
-o, --output=<output-file>
The file to write the upgraded config to (use - to write to STDOUT). Defaults to STDOUT.
--overwrite Overwrite the input file with the upgraded config
--nested=PATH Path to the nested config object (e.g., 'global.unattended.configuration')
When specified, only the config at this path is upgraded; other content is preserved
-s, --schema-version=VERSION
Target schema version to upgrade to (defaults to latest)
Examples:
Upgrade a config file and write to stdout
develocityctl config-file upgrade config.yaml
Upgrade a config file and write to a new file
develocityctl config-file upgrade config.yaml -o upgraded-config.yaml
Upgrade a config file in place
develocityctl config-file upgrade config.yaml --overwrite
Upgrade a nested config in a Helm values file
develocityctl config-file upgrade values.yaml --nested global.unattended.configuration -o upgraded-values.yaml
Upgrade a config file to a specific schema version
develocityctl config-file upgrade config.yaml --schema-version 10
build-scan
Usage: develocityctl build-scan COMMAND Work with Build Scan data Commands: copy Copy Build Scan data between Develocity installations. Run 'develocityctl build-scan COMMAND --help' for more information on a command.
copy
Usage: develocityctl build-scan copy --sourceUrl=<url> [--sourceAccessKeyFile=<access-key-file>] --destinationUrl=<url>
[--destinationAccessKeyFile=<access-key-file>] [--parallelUploads=<number>]
[--copyScanDataSince=<2021-05-12>] [--startWithBuildId=<Build Scan ID, e.g.
a6cuc7elowjmq>] [--failuresFile=<failures.txt>] [--allowUntrustedSsl]
[[--discardProjectId] | --projectId=<project-id>]
Copy Build Scan data between Develocity installations.
Options:
--sourceUrl=<url> URL of the source system
--sourceAccessKeyFile=<access-key-file>
Path to the file containing access key to the source system, if required to view scans
--destinationUrl=<url>
URL of the destination system
--destinationAccessKeyFile=<access-key-file>
Path to the file containing access key to the destination system, if required to publish
scans
--parallelUploads=<number>
Max number of concurrent uploads to the destination system
--copyScanDataSince=<2021-05-12>
All scans received earlier than this date are copied as deleted scans only, with the
current date supplied to the target system as the deletion timestamp.
--startWithBuildId=<Build Scan ID, e.g. a6cuc7elowjmq>
Starts copying backwards since the build scan before provided build scan id (excluding it),
all later build scans are skipped. If not provided starts with latest available build
scan. Useful to restart the copying from last copied build scan.
--failuresFile=<failures.txt>
File path to store ids of build scans which failed to be copied.
--discardProjectId Discard any project association stored in the source server when copying build scans to the
destination server.
--projectId=<project-id>
Project ID to assign to all build scans when copying them to the destination server
--allowUntrustedSsl Allows connecting over HTTPS to servers which don't have valid SSL certificates
Source system access key can be also specified using SOURCE_ACCESS_KEY environment variable.
Destination system access key can be also specified using DESTINATION_ACCESS_KEY environment variable.
database
Usage: develocityctl database COMMAND Execute commands on the Develocity database Commands: check-index Check Develocity database indexes for corruption query Execute queries against the Develocity database Run 'develocityctl database COMMAND --help' for more information on a command.
check-index
Usage: develocityctl database check-index
Check Develocity database indexes for corruption
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
query
Usage: develocityctl database query [--db-schema=<schema>] [--psql-options=<options>] [--quiet] [--db-url=<url>]
(--query=<sql> | --query-file=<file>) [--no-output-file | --output-file=<file>]
Execute queries against the Develocity database
Options:
--query=<sql> SQL query to be executed
--query-file=<file> Run the query contained in the provided file
--no-output-file Don't write the output to any file
--output-file=<file> Write the output to the provided filename. Defaults to 'database_query_output_<timestamp>.
txt'.
--db-schema=<schema> Run this script against the provided schema. Defaults to 'build_scans'.
--psql-options=<options>
Options to pass to psql, e.g '-t -A'
--quiet Don't print the output in the console
--db-url=<url> Database URL to connect to if Develocity is down. Requires psql to be installed locally.
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
JAR Examples:
develocityctl database query --db-schema=build_cache --query='SELECT * FROM pg_settings'
develocityctl database query --query-file=my_query.sql --output-file=my_output.txt --quiet --psql-options='-t -A'
develocityctl database query --query-url='https://git.io/JOLli'
PGPASSWORD=s3cr4t develocityctl database query --query='SELECT version()' --db-url=postgresql://user@dbhost.
mynetwork.com/gradle_enterprise
license
Usage: develocityctl license COMMAND Print license file details and convert between license file formats Commands: convert Reads a Develocity license in any format and writes back out it in a specified format Run 'develocityctl license COMMAND --help' for more information on a command.
convert
Usage: develocityctl license convert [-o=<output-file>] -f=<format> <license-file>
Reads a Develocity license in any format and writes back out it in a specified format
Parameters:
<license-file> The license file to convert (use - to read from STDIN)
Options:
-o, --output=<output-file>
Where to write the converted license file (use - to write to STDOUT). Defaults to STDOUT.
-f, --format=<format> Format to convert license to (formats: standard, compact).
JAR Examples:
develocityctl license convert ge.license -o ge_compact.license -f compact
support-bundle
Usage: develocityctl support-bundle [--skip-operator] [--fetch-logs-max-time=<period>]
[--fetch-metrics-max-time=<period>] [--include-proxy-access-log]
[--include-build-insight-metrics] [--since-time=<since>] [--until-time=<until>]
[[-d=<output-directory>]]
Create a support bundle for sending to Gradle support
Bundle is a Zip file saved by default in the current working directory.
Options:
-d, --directory=<output-directory>
Directory to write the generated bundle zip file to.
--skip-operator Trigger support bundle generation without the use of the Develocity Operator.
Generate it locally, instead. Some data won't be captured in that mode.
It's useful if generation through the Operator fails.
--fetch-logs-max-time=<period>
The maximum time allowed for collecting log messages into the support bundle.
Accepted values are in ISO-8601 duration format PnDTnHnMn.nS.
If omitted, it defaults to PT30M (30 minutes) and if the duration
is zero or a negative value, the export of log messages is skipped completely.
For example `--fetch-logs-max-time=PT20M` will stop gathering logs after 20 minutes.
--fetch-metrics-max-time=<period>
The maximum time allowed for collecting metrics into the support bundle.
Accepted values are in ISO-8601 duration format PnDTnHnMn.nS.
If omitted, it defaults to PT30M (30 minutes) and if the duration
is zero or a negative value, the export of metrics is skipped completely.
For example `--fetch-metrics-max-time=PT20M` will stop gathering metrics after 20 minutes.
--include-proxy-access-log
The proxy access log contains extensive details that significantly slow down
support bundle generation. It's usually unnecessary for most support cases, except
when troubleshooting request routing issues that result in HTTP 400 or 500 status codes.
To include the proxy access log in the support bundle, specify this option.
--include-build-insight-metrics
Include build insight metrics data (performance dashboard and trends data) in the support
bundle.
Build insight metrics are not included by default.
--since-time=<since> Overrides the default start time of the collection period for data
(such as logs or metrics stored in object storage) in a support bundle.
Time limits apply regardless of the value you enter:
- Logs: Maximum of 7 days
- Metrics: Maximum of 30 days
This start time setting applies uniformly to all data collections.
The format should be a RFC3339 timestamp, for example:
2023-12-24T10:00:00Z (UTC timezone) or 2023-12-23T17:30:00+05:00 (UTC+5 timezone).
If left blank, the following default start times will be used:
- Logs: 7 days ago
- Proxy access log: 12 hours ago
- Metrics: 30 days ago
--until-time=<until> Overrides the default end time of the collection period for data
(such as logs or metrics) in a support bundle.
When specified, this value applies to all data collections uniformly.
The format should be a RFC3339 timestamp, for example:
2023-12-24T10:00:00Z (UTC timezone) or 2023-12-23T17:30:00+05:00 (UTC+5 timezone).
If left blank, the current time ('now') will be used as the end time.
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
system
Usage: develocityctl system COMMAND System command to interact with Develocity Commands: disable-default-identity-provider Disable the default identity provider get-default-system-password Get the default Develocity system password reset-system-password Reset Develocity system password stop Stop all Develocity components start Start Develocity components restart Restart Develocity test-notification Execute a notification test Run 'develocityctl system COMMAND --help' for more information on a command.
disable-default-identity-provider
Usage: develocityctl system disable-default-identity-provider
Disable the default identity provider
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
get-default-system-password
Usage: develocityctl system get-default-system-password
Get the default Develocity system password
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
reset-system-password
Usage: develocityctl system reset-system-password
Reset Develocity system password
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
stop
Usage: develocityctl system stop
Stop all Develocity components
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
start
Usage: develocityctl system start
Start Develocity components
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
restart
Usage: develocityctl system restart
Restart Develocity
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
test-notification
Usage: develocityctl system test-notification
Execute a notification test
Kubernetes cluster options:
--kube-ctx=<context> The Kubernetes context name. Defaults to current context if one is selected.
--kube-ns=<namespace> The namespace containing Develocity.
--kube-url=<url> The Kubernetes API URL for the cluster.
--kube-token=<token> The OAuth token to use.
--kube-trust-certs Ignore certificate validation errors.
If you have any questions or need any assistance contact the Develocity support team or your customer success representative.