Artifact Cache CLI Commands Reference

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 develocity-artifact-cache-cli.jar [GLOBAL OPTIONS] COMMAND

-v, --version

Prints the version information and exits.

java -jar develocity-artifact-cache-cli.jar --version

Commands Overview

The Artifact Cache CLI provides two primary commands:

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

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

restore Command

Restores content from the Develocity Artifact Cache and Setup Cache.

Syntax

java -jar develocity-artifact-cache-cli.jar restore [OPTIONS]

Connection Options

One of --dv-server or --dv-edge is required.

--dv-server=<url>

The Develocity server URL. The Artifact Cache CLI uses Edge discovery to find the optimal Edge to connect to.

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

--dv-edge=<url>

The Develocity Edge URL. When specified, the Artifact Cache CLI connects directly to this Edge instead of automatically discovering the user’s preferred Edge location via the Develocity server.

Cannot be used together with --dv-server.

Example: --dv-edge=https://edge.example.com

Cache Selection Options

At least one build tool has to be configured to indicate which build tool content to restore. Build tools are autodetected by default, but can also be disabled or configured explicitly.

--autodetect=<tool>[,<tool>…​]

Specifies which build tool to autodetect and cache for.

Defaults to all values.

Valid values: MAVEN, GRADLE, NPM

--no-autodetect=<tool>[,<tool>…​]

Specifies which build tool to exclude from autodetection.

Valid values: MAVEN, GRADLE, NPM

--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

--disable-artifact-cache

Disable storing to the Artifact Cache.

 Storing to the Artifact Cache requires that the entitlement Artifact Cache is enabled on your Develocity license. Consider disabling the Artifact Cache if the entitlement is not enabled. Otherwise, the Artifact Cache CLI will show a warning.
--disable-setup-cache

Disable storing to the Setup Cache.

 Storing to the Setup Cache requires that the entitlement Setup Cache is enabled on your Develocity license. Consider disabling the Setup Cache if the entitlement is not enabled. Otherwise, the Artifact Cache CLI will show a warning.

Image Management Options

--image-name=<name>

Name to use when restoring this Develocity Artifact Cache 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: 0 (automatic — uses the number of available processors multiplied by the concurrency factor)

Example: --operation-concurrency=4

--operation-concurrency-factor=<number>

A multiplier applied to the number of available processors when --operation-concurrency is set to 0 (automatic).

Default: 1.0

Example: --operation-concurrency-factor=2

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 diagnostic data to, including logs and profiling recordings.

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 develocity-artifact-cache-cli.jar 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 Cache and Setup Cache.

Syntax

java -jar develocity-artifact-cache-cli.jar store [OPTIONS]

Connection Options

One of --dv-server or --dv-edge is required.

--dv-server=<url>

The Develocity server URL. The Artifact Cache CLI uses Edge discovery to find the optimal Edge to connect to.

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

--dv-edge=<url>

The Develocity Edge URL. When specified, the Artifact Cache CLI connects directly to this Edge instead of automatically discovering the user’s preferred Edge location via the Develocity server.

Cannot be used together with --dv-server.

Example: --dv-edge=https://edge.example.com

Cache Selection Options

At least one build tool has to be configured to indicate which build tool content to store. Build tools are autodetected by default, but can also be disabled or configured explicitly.

--autodetect=<tool>[,<tool>…​]

Specifies which build tool to autodetect and cache for.

Defaults to all values.

Valid values: MAVEN, GRADLE, NPM

--no-autodetect=<tool>[,<tool>…​]

Specifies which build tool to exclude from autodetection.

Valid values: MAVEN, GRADLE, NPM

--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

--disable-artifact-cache

Disable storing to the Artifact Cache.

--disable-setup-cache

Disable storing to the Setup Cache.

Image Management Options

--image-name=<name>

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

Unlike the restore command, only a single image name can be specified for store.

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: 0 (automatic — uses the number of available processors multiplied by the concurrency factor)

Example: --operation-concurrency=4

--operation-concurrency-factor=<number>

A multiplier applied to the number of available processors when --operation-concurrency is set to 0 (automatic).

Default: 1

Example: --operation-concurrency-factor=2

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 diagnostic data to, including logs and profiling recordings.

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>. When using --dv-edge, use the Edge host as the key host.

Example: DEVELOCITY_ACCESS_KEY=develocity.example.com=abcd1234efgh5678

DEVELOCITY_ARTIFACT_CACHE_BRANCH_NAME

Overrides the branch name used for automatic image name generation. Applies to all supported CI providers.

DEVELOCITY_ARTIFACT_CACHE_BASE_BRANCH_NAME

Overrides the base (fallback) branch name used for automatic image name generation. Applies to all supported CI providers.

Build Tool Autodetection

By default, the Artifact Cache CLI automatically detects which build tools are in use by checking for the presence of standard tool home directories.

Gradle:

  • Checks the GRADLE_USER_HOME environment variable first.

  • Falls back to ~/.gradle if the variable is not set.

Maven:

  • Checks ~/.m2 for the Maven home directory.

  • For the local repository path, parses settings.xml (if present) for a custom <localRepository> configuration. Falls back to ~/.m2/repository.

npm:

  • Checks the NPM_CONFIG_CACHE environment variable first.

  • Falls back to ~/.npm if the variable is not set.

If a build tool home directory is not found, that tool is skipped. You can override autodetection with explicit --gradle-home, --maven-home, --maven-repository, or --npm-home options. Use --no-autodetect=<tool> to exclude specific tools from autodetection, or --autodetect=<tool> to limit autodetection to specific tools.

Error Handling

The Artifact Cache CLI is designed to never fail a CI build due to cache-related errors. If a transient error occurs — such as a network timeout, an unreachable Edge, or a missing entitlement — the Artifact Cache CLI logs the error and exits with code 0.

This means your CI pipeline will continue to function even if caching is temporarily unavailable. To detect cache errors programmatically, check the --cache-metrics-file output or enable --verbose logging.