# atmos ci cache

The `atmos ci cache` command group restores a well-known cache directory (the toolchain install path and anything else under the Atmos cache root) at the start of a CI step and saves it back at the end, using the active CI provider's cache store — the same store that `actions/cache` uses. This warm-starts the toolchain and other regenerable artifacts across CI jobs and workflow runs.

> ⚠️ Experimental

**Configure the CI Cache**

Learn how to enable the cache, choose automatic vs. manual behavior, and customize the cache key, paths, and restore-keys in your `atmos.yaml`.

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

## Lifecycle

The cache lifecycle can run **in a single Atmos invocation** (automatic restore-on-start and save-on-end) or be **spread across CI steps** with the explicit subcommands:

**File:** `Spread across steps`

```
- run: atmos ci cache restore   # step 1: warm the cache
- run: atmos toolchain install  # step 2: use it (installs only what's missing)
- run: atmos ci cache save      # step 3: persist it for the next run
```

Both styles share one implementation. "Automatic" is just the same idempotent operations invoked by the process lifecycle, so manual and automatic invocations never double-execute (cache entries are write-once; an exact-key hit at restore time skips the save).

## Requirements

Saving and restoring content require running inside a supported CI provider (GitHub Actions today), which exposes the runtime cache credentials. Outside CI, these commands report that the cache is unavailable. The cache must also be enabled — see the [configuration reference](/cli/configuration/ci/cache).

## Subcommands

## Related

- [CI Cache Configuration](/cli/configuration/ci/cache) - Configure the cache in `atmos.yaml`
- [CI Configuration](/cli/configuration/ci) - Configure CI integration
- [`atmos toolchain`](/cli/commands/toolchain/usage) - Manage the toolchain that the cache warm-starts