Artifact Cache CLI Commands Reference

Limited Availability

The Develocity Artifact and Setup Cache is in Limited Availability.

Please contact the Develocity support team to get started with Develocity Artifact and Setup Cache.

This section provides an overview of the commands available in the Artifact Cache CLI. Each command is described along with its options and their functionalities.

Global Options

java -jar {cli-name} [GLOBAL OPTIONS] COMMAND

-v, --version

Prints the version information and exits.

java -jar {cli-name} --version

Commands Overview

The Artifact Cache CLI provides two primary commands:

  • store - Stores content in the Develocity Artifact and Setup Cache

  • restore - Restores content from the Develocity Artifact and Setup Cache

restore Command

Restores content from the Develocity Artifact and Setup Cache.

Syntax

java -jar {cli-name} restore [OPTIONS]

Required Options

--dv-server=<url>

The Develocity server URL.

Example: --dv-server=https://develocity.example.com

Cache Selection Options

At least one of the following must be specified to indicate which build tool content to restore:

--gradle-home=<path>

Location to restore Gradle content.

Example: --gradle-home=$HOME/.gradle

--maven-home=<path>

Location to restore Maven content.

Example: --maven-home=$HOME/.m2

--maven-repository=<path>

Location to restore the Maven local repository. Defaults to ←-maven-home>/repository.

Example: --maven-repository=/custom/path/to/repo

 Required when using a custom Maven repository path (e.g., via -Dmaven.repo.local or localRepository in settings.xml).
--npm-home=<path>

Location to restore npm content.

Example: --npm-home=$HOME/.npm

Image Management Options

--image-name=<name>

Name to use when restoring this Develocity Artifact and Setup Cache image. If absent, an image name will be generated automatically for supported CI providers (GitHub Actions, Jenkins).

Can be specified multiple times to provide fallback image names.

Example: --image-name=my-project-main --image-name=my-project-fallback

--refresh-every-period=<period>

Period in ISO-8601 format (without time component) after which the cache is refreshed.

Default: P1M (one month)

Example: --refresh-every-period=P2W (refresh every 2 weeks)

When combined with --refresh-every-generation, the first condition to trigger will refresh the cache.

--refresh-every-generation=<number>

Number of generations after which the cache is refreshed (counting starts at 1).

Example: --refresh-every-generation=10

Combines with --refresh-every-period - the first condition to trigger will refresh the cache.

--refresh-now

Forces an unconditional refresh of the cache. Use this to manually trigger a cache refresh, typically when you want to rebuild the image from scratch.

Example: --refresh-now

Performance Options

--timeout=<duration>

Time to wait for the command to complete, in ISO-8601 format.

Default: PT10M (10 minutes)

Example: --timeout=PT15M (15 minutes)

--operation-timeout=<duration>

Time to wait for an individual operation to complete, in ISO-8601 format.

Default: PT60S (60 seconds)

Example: --operation-timeout=PT120S (2 minutes)

--operation-concurrency=<number>

The maximum number of parallel operations to run.

Default: Number of processors (or set to 0 for automatic detection)

Example: --operation-concurrency=4

Security Options

--allow-untrusted-server

Allows untrusted SSL communication.

 Only use this in development or testing environments. Never use in production.

Diagnostic Options

--verbose

Enables verbose logging for the command. Useful for troubleshooting connection or performance issues.

--reporting-directory=<path>

Directory to write reports and logs to.

Default: <home>/.develocity/artifact-cache/

Example: --reporting-directory=/tmp/ac-logs

--cache-metrics-file=<file>

If set, stores cache metrics to this file. Useful for analyzing cache performance and hit rates.

Example: --cache-metrics-file=cache-metrics.json

--dry-run

Contacts Develocity and outputs statistics about artifacts that would have been downloaded from the Develocity Edge if the feature had been used. No actual restore operations are performed.

Use this to estimate potential time savings before fully implementing Artifact Cache.

Complete Example

java -jar {cli-name} restore \
  --dv-server=https://develocity.example.com \
  --gradle-home=$HOME/.gradle \
  --image-name=my-project-main \
  --refresh-every-period=P1M \
  --verbose

store Command

Stores content in the Develocity Artifact and Setup Cache.

Syntax

java -jar {cli-name} store [OPTIONS]

Required Options

--dv-server=<url>

The Develocity server URL.

Example: --dv-server=https://develocity.example.com

Cache Selection Options

At least one of the following must be specified to indicate which build tool content to store:

--gradle-home=<path>

Location of Gradle User Home directory to store. Activates Gradle support if provided.

Example: --gradle-home=$HOME/.gradle

--maven-home=<path>

Location of Maven M2 directory to store. Activates Maven support if provided.

Example: --maven-home=$HOME/.m2

--maven-repository=<path>

Location of the Maven local repository to store. Defaults to <--maven-home>/repository.

Example: --maven-repository=/custom/path/to/repo

 Required when using a custom Maven repository path (e.g., via -Dmaven.repo.local or localRepository in settings.xml).
--npm-home=<path>

Location of the npm cache directory to store. Activates npm support if provided.

Example: --npm-home=$HOME/.npm

Image Management Options

--image-name=<name>

Name to use when storing this Develocity Artifact and Setup Cache image. If absent, an image name will be generated automatically for supported CI providers (GitHub Actions, Jenkins).

Example: --image-name=my-project-main

Performance Options

--timeout=<duration>

Time to wait for the command to complete, in ISO-8601 format.

Default: PT10M (10 minutes)

Example: --timeout=PT15M (15 minutes)

--operation-timeout=<duration>

Time to wait for an individual operation to complete, in ISO-8601 format.

Default: PT60S (60 seconds)

Example: --operation-timeout=PT120S (2 minutes)

--operation-concurrency=<number>

The maximum number of parallel operations to run.

Default: Number of processors (or set to 0 for automatic detection)

Example: --operation-concurrency=4

Security Options

--allow-untrusted-server

Allows untrusted SSL communication.

 Only use this in development or testing environments. Never use in production.

Diagnostic Options

--verbose

Enables verbose logging for the command. Useful for troubleshooting connection or performance issues.

--reporting-directory=<path>

Directory to write reports and logs to.

Default: <home>/.develocity/artifact-cache/

Example: --reporting-directory=/tmp/ac-logs

--cache-metrics-file=<file>

If set, stores cache metrics to this file. Useful for analyzing cache performance and upload statistics.

Example: --cache-metrics-file=cache-metrics.json

--dry-run

Displays statistics about discovered artifacts that would have been stored if the feature had been used. No actual store operations are performed.

Use this to estimate network usage and storage requirements before fully implementing Artifact Cache.

Complete Example

java -jar develocity-artifact-cache-cli.jar store \ --dv-server=https://develocity.example.com \ --gradle-home=$HOME/.gradle \ --image-name=my-project-main \ --verbose

Environment Variables

The Artifact Cache CLI respects the following environment variables:

DEVELOCITY_ACCESS_KEY

The Develocity access key in the format <host_name>=<access_key_value>.

Example: DEVELOCITY_ACCESS_KEY=develocity.example.com=abcd1234efgh5678