Skip to main content

atmos ci cache restore

Restore the CI cache into the well-known cache directory. The exact key is looked up first, then the configured restore-keys (prefix matches) are tried in order. On a hit, the archive is extracted into the cache root. Restore is idempotent within a lifecycle — once a key has been restored, repeat restores are no-ops.

Experimental
Runs only inside a CI runner

restore transfers cache content through the CI provider's runtime cache API, which requires credentials that exist only inside a runner (on GitHub Actions: ACTIONS_RUNTIME_TOKEN and ACTIONS_RESULTS_URL). Run outside a runner it reports that the cache is unavailable. To manage the cache from your workstation, use list and delete.

Configure the CI Cache

Configure the cache key, restore-keys, and paths used by this command in your atmos.yaml.

atmos ci cache restore

Usage​

atmos ci cache restore [flags]

With no flags, the cache key and paths come from the ci.cache configuration (the default key is derived from the toolchain lockfile).

Examples​

# Restore using the configured (or default) key
atmos ci cache restore

# Restore an explicit key with prefix fallbacks
atmos ci cache restore --key="toolchain-linux-amd64-abc123" \
  --restore-key="toolchain-linux-amd64-"

# Restore only specific root-relative subpaths
atmos ci cache restore --path=toolchain

Flags​

--key / -k
Exact cache key to restore. Defaults to a key derived from the toolchain lockfile plus OS/arch.
--restore-key
Prefix fallback keys tried in order when the exact key is absent. Repeatable.
--path / -p
Root-relative subpaths to restore. Defaults to the entire cache root. Repeatable.
--root
Override the cache root directory (defaults to the Atmos XDG cache directory, e.g. ~/.cache/atmos).

Environment Variables​

ATMOS_CI_CACHE_ENABLED
Must be true (or ci.cache.enabled: true in atmos.yaml) for the command to run.
ATMOS_CI_CACHE_KEY
Overrides --key.
ACTIONS_RUNTIME_TOKEN / ACTIONS_RESULTS_URL
Provided automatically inside a GitHub Actions runner; required for the GitHub Actions cache backend.