# atmos ci cache save

Archive the cache root (the toolchain and anything else under it) and upload it under the cache key. Cache entries are write-once: when the exact key was an exact hit at restore time (content unchanged) or has already been saved this lifecycle, the save is skipped.

> ⚠️ Experimental

:::info Runs only inside a CI runner
`save` 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 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 save [flags]
```

## Examples

```shell
# Save using the configured (or default) key
atmos ci cache save

# Save under an explicit key
atmos ci cache save --key="toolchain-linux-amd64-abc123"

# Save only specific root-relative subpaths
atmos ci cache save --path=toolchain
```

## Flags

- **`--key` / `-k`**
  Exact cache key to save under. Defaults to a key derived from the toolchain lockfile plus OS/arch.
- **`--path` / `-p`**
  Root-relative subpaths to save. 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 restore`](/cli/commands/ci/cache/restore) - Restore the cache
- [CI Cache Configuration](/cli/configuration/ci/cache) - Configure the cache