# 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

:::info 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`](/cli/commands/ci/cache/list) and [`delete`](/cli/commands/ci/cache/delete).
:::

**Configure the CI Cache**

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

CI Cache Configuration Reference[Read more](/cli/configuration/ci/cache)

## Usage

```shell
atmos ci cache restore [flags]
```

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

## Examples

```shell
# 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.

## Related

- [`atmos ci cache save`](/cli/commands/ci/cache/save) - Save the cache
- [CI Cache Configuration](/cli/configuration/ci/cache) - Configure the cache