# Caches with the CLI

> List, create, test, update and delete S3-compatible runner caches, and attach them to runners from the terminal.

Source: https://managerunners.com/docs/cli/caches/

A cache stores the GitLab CI `cache:` of your runners in an S3-compatible bucket. [Caches](https://managerunners.com/docs/manual/caches/) in the manual explains providers, sharing and what recreates runners. Reading caches needs the `runners:read` scope, which the CLI's login token has; changes and `cache test` need `runners:write`. An explicit cache id adds no cache-read requirement: `cache test --id`, `cache delete --id` and `runner create --cache <id>` work with `runners:write` alone, while `runner update` still needs `runners:read` and `runners:write` because it reads the runner first. Resolving a cache name needs `runners:read`:

```sh
manage-runners auth login --profile default --scope runners:write
```

## List and inspect

```sh
manage-runners cache list
manage-runners cache get --name "Team cache"
```

Each cache shows its connection settings, whether it is `shared`, and `usedBy`, the runners that use it. The secret key is never returned. `--name` matches the exact name first and then a unique name in any letter case.

## Create a cache

Pass the secret key on standard input or through a named environment variable, never as a flag value:

```sh
printf '%s' "$S3_SECRET_KEY" | manage-runners cache create \
  --name "Team cache" \
  --server-address fsn1.your-objectstorage.com \
  --bucket ci-cache \
  --region fsn1 \
  --access-key-id "$S3_ACCESS_KEY_ID" \
  --secret-key-stdin
```

| Flag | Required | Description |
| --- | --- | --- |
| `--name` | yes | Unique within the organization |
| `--server-address` | yes | Host and optional port, without `https://` |
| `--bucket` | yes | Bucket name |
| `--region` | yes | Bucket region, for example `fsn1`, `eu-central-1` or `auto` |
| `--access-key-id` | yes | Access key ID |
| `--secret-key-stdin` or `--secret-key-env` | yes | Where to read the secret key; in a terminal the CLI asks instead |
| `--path-prefix` | no | Folder inside the bucket |
| `--shared on\|off` | no | Share entries between runners; `on` by default |
| `--path-style auto\|path\|virtual` | no | Addressing style; `auto` by default |
| `--insecure` | no | Plain HTTP instead of HTTPS |

## Test a cache

```sh
manage-runners cache test --name "Team cache"
manage-runners cache test --server-address s3.eu-central-1.amazonaws.com --bucket ci-cache \
  --region eu-central-1 --access-key-id "$S3_ACCESS_KEY_ID" --secret-key-env S3_SECRET_KEY
```

The test writes, reads and deletes a small object. It only works for HTTPS endpoints with a public address. A failed test exits with code 7 and `CACHE_TEST_FAILED`; `error.details.result.code` names the cause, for example `AUTHENTICATION_FAILED`, `BUCKET_NOT_FOUND`, `ACCESS_DENIED`, `TLS_ERROR` or `UNREACHABLE`.

## Use a cache on a runner

```sh
manage-runners runner create ... --cache "Team cache"
manage-runners runner update --id 812999368881481087 --cache "Team cache" --yes
manage-runners runner update --id 812999368881481087 --no-cache --yes
```

Changing a runner's cache recreates an active runner's server, so `runner update` asks for confirmation or needs `--yes`. `runner get` and `runner list` show `cacheId` and `cacheName`.

## Update a cache

```sh
manage-runners cache update --name "Team cache" --new-name "Build cache"
manage-runners cache update --name "Team cache" --shared off --yes
printf '%s' "$NEW_SECRET" | manage-runners cache update --id 893531162387173432 --secret-key-stdin --yes
```

Flags you leave out keep their current values, and the stored secret key is kept unless you pass a new one. Renaming never affects runners. Any other change recreates the servers of the active runners that use the cache: without `--yes`, the command fails with `CACHE_RECREATE_REQUIRED` and lists the runners (in a terminal it asks instead). Runners listed with `recreate: false` are unknown: they are not recreated and keep the previous settings until edited or recreated. With `--yes`, the output lists the recreated runners under `recreatedRunners` and reports `paid_resource_effect: "recreate"`. While a runner that uses the cache is being created, resumed or edited, the update fails with `RUNNER_LOCKED` (exit 6) and names it.

## Delete a cache

```sh
manage-runners cache delete --id 893531162387173432 --yes --confirm 893531162387173432
```

A cache that runners use cannot be deleted: the command fails with `CACHE_IN_USE` (exit 6) and lists the runners. Remove the cache from them first. Deleting does not touch the bucket.