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.

DEVELOCITY_ACCESS_KEY must contain an entry for the Edge host. An entry for the Develocity server host doesn’t authenticate against the Edge, and may be present alongside the Edge entry without effect. See Connecting Without Edge Discovery.

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

Cache Selection Options

At least one tool has to be configured to indicate which tool content to restore. Tools are auto-detected by default, but can also be disabled or configured explicitly.

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

Specifies which tool to auto-detect and cache for.

Defaults to all values.

Valid values: CYPRESS, GRADLE, MAVEN, NPM, PIP, PLAYWRIGHT, SONAR

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

Specifies which tool to exclude from auto-detection.

Valid values: CYPRESS, GRADLE, MAVEN, NPM, PIP, PLAYWRIGHT, SONAR

--cypress-home=<path>

Location to restore the Cypress binary cache.

Example: --cypress-home=$HOME/.cache/Cypress

Cypress binaries are restored only from a matching host platform, as described in Cypress Host Platforms.

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

--pip-home=<path>

Location to restore the pip download cache.

Example: --pip-home=$HOME/.cache/pip

--playwright-home=<path>

Location to restore Playwright browsers.

Example: --playwright-home=$HOME/.cache/ms-playwright

Playwright browsers are restored only from a matching host platform, as described in Playwright Host Platforms.

--sonar-home=<path>

Location to restore Sonar content.

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

--disable-artifact-cache

Disable restoring from the Artifact Cache.

 Restoring from the Artifact Cache requires that the entitlement Artifact Cache is enabled on your Develocity license. Consider disabling the Artifact Cache if the entitlement isn’t enabled. Otherwise, the Artifact Cache CLI will show a warning.
--disable-setup-cache

Disable restoring from the Setup Cache.

 Restoring from the Setup Cache requires that the entitlement Setup Cache is enabled on your Develocity license. Consider disabling the Setup Cache if the entitlement isn’t 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.

DEVELOCITY_ACCESS_KEY must contain an entry for the Edge host. An entry for the Develocity server host doesn’t authenticate against the Edge, and may be present alongside the Edge entry without effect. See Connecting Without Edge Discovery.

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

Cache Selection Options

At least one tool has to be configured to indicate which tool content to store. Tools are auto-detected by default, but can also be disabled or configured explicitly.

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

Specifies which tool to auto-detect and cache for.

Defaults to all values.

Valid values: CYPRESS, GRADLE, MAVEN, NPM, PIP, PLAYWRIGHT, SONAR

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

Specifies which tool to exclude from auto-detection.

Valid values: CYPRESS, GRADLE, MAVEN, NPM, PIP, PLAYWRIGHT, SONAR

--cypress-home=<path>

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

Example: --cypress-home=$HOME/.cache/Cypress

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

--pip-home=<path>

Location of the pip download cache to store. Activates pip support if provided.

Example: --pip-home=$HOME/.cache/pip

--playwright-home=<path>

Location of the Playwright browsers directory to store. Activates Playwright support if provided.

Example: --playwright-home=$HOME/.cache/ms-playwright

--sonar-home=<path>

Location of the Sonar user home directory to store. Activates Sonar support if provided.

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

--disable-artifact-cache

Disable storing to the Artifact Cache.

--disable-setup-cache

Disable storing to the Setup Cache.

--include-snapshot-dependencies

Include SNAPSHOT dependencies in the stored image for Maven.

See Maven Snapshot Dependencies Caching for details.

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

The value can hold entries for several hosts, separated by semicolons. The Artifact Cache CLI uses the entry matching the host it connects to and ignores the rest.

Example: DEVELOCITY_ACCESS_KEY=develocity.example.com=abcd1234efgh5678;edge.example.com=ijkl9012mnop3456

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.

Tool Auto-Detection

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

Cypress:

The Artifact Cache CLI resolves the Cypress binary cache the same way Cypress does:

  • Checks the CYPRESS_CACHE_FOLDER environment variable first. Surrounding whitespace is trimmed, and one surrounding pair of double quotes is removed. Windows cmd keeps the quotes of set CYPRESS_CACHE_FOLDER="C:\cache" in the value itself.

  • Skips Cypress auto-detection when CYPRESS_CACHE_FOLDER holds a relative path. Cypress resolves a relative value against the package root during the npm postinstall hook, and against the working directory afterwards. The two can name different directories. Pass --cypress-home with an absolute path instead.

  • On Linux, falls back to $XDG_CACHE_HOME/Cypress if XDG_CACHE_HOME is set, and to ~/.cache/Cypress otherwise.

  • On macOS, falls back to ~/Library/Caches/Cypress.

  • On Windows, falls back to %LOCALAPPDATA%\Cypress\Cache, or to ~\AppData\Local\Cypress\Cache if LOCALAPPDATA isn’t set.

A cache folder set through npm configuration or a package.json config block isn’t detected. Pass --cypress-home for those setups.

Gradle:

  • Checks the GRADLE_USER_HOME environment variable first.

  • Falls back to ~/.gradle if the variable isn’t 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 isn’t set.

pip:

  • Checks the PIP_CACHE_DIR environment variable first.

  • Falls back to $XDG_CACHE_HOME/pip if XDG_CACHE_HOME is set.

  • Otherwise falls back to the platform default (~/.cache/pip on Linux, ~/Library/Caches/pip on macOS, %LOCALAPPDATA%\pip\Cache on Windows).

Playwright:

The Artifact Cache CLI resolves the Playwright browsers registry the same way Playwright does:

  • Checks the PLAYWRIGHT_BROWSERS_PATH environment variable first, using the value exactly as given.

  • Skips Playwright caching when PLAYWRIGHT_BROWSERS_PATH is 0. Playwright then installs browsers inside the installed package, under node_modules for a JavaScript project. That is workspace content, not a shared tool cache, so the Artifact Cache CLI logs the reason.

  • Resolves a relative PLAYWRIGHT_BROWSERS_PATH against INIT_CWD when that variable is set (npm exports it), and against the current directory otherwise.

  • On Linux, falls back to $XDG_CACHE_HOME/ms-playwright if XDG_CACHE_HOME is set, and to ~/.cache/ms-playwright otherwise.

  • On macOS, falls back to ~/Library/Caches/ms-playwright.

  • On Windows, falls back to %LOCALAPPDATA%\ms-playwright, or to ~\AppData\Local\ms-playwright if LOCALAPPDATA isn’t set.

Sonar:

  • Checks the SONAR_USER_HOME environment variable first.

  • Falls back to ~/.sonar if the variable isn’t set.

On restore, the Artifact Cache CLI creates the detected tool home directory if it does not already exist so the cache can be written to it. On store, a tool is skipped when its detected tool home directory is absent.

You can override auto-detection with explicit --cypress-home, --gradle-home, --maven-home, --maven-repository, --npm-home, --pip-home, --playwright-home, or --sonar-home options. Use --no-autodetect=<tool> to exclude specific tools from auto-detection, or --autodetect=<tool> to limit auto-detection 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.