> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blacksmith.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache

> List and delete cache entries from the terminal

The `blacksmith cache` commands let you inspect and clean up a repository's cache data programmatically. This is especially useful for repositories with many generated or parameterized cache keys.

## Permissions

Listing requires the user who created the CLI token to be able to see the target repository on GitHub (any permission level, including read) — the same visibility rule the dashboard enforces. Deleting (`delete` and `clear`) additionally requires the user who created the CLI token (via `blacksmith auth login`) to have **write access** to the target repository on GitHub (the `WRITE`, `MAINTAIN`, or `ADMIN` role) — the same rule the dashboard enforces. Tokens not tied to a user account cannot delete; re-authenticate with `blacksmith auth login` to mint a token tied to your account. [Organization tokens](/blacksmith-cli/overview#token-types) are exempt from these per-repository checks and can list and delete for any repository in the organization.

Two kinds of cache entries are surfaced, distinguished by the `type` field in list output:

| Type      | What it is                                                                                                                                    |
| :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| `actions` | GitHub Actions cache entries (from `actions/cache` and Blacksmith's transparent caching). One row per key/version/scope variant.              |
| `bazel`   | Bazel remote build cache namespaces. One row per build tool and architecture, with `size_bytes` reflecting the namespace's storage footprint. |

## `blacksmith cache list`

Lists cache entries for a repository.

```bash theme={"system"}
blacksmith cache list --repo my-org/my-repo --format table
```

```
TYPE     KEY                              VERSION    SIZE_MB  ARCH   SCOPE  TRANSPARENT  LAST_USED_AT
actions  node-modules-a1b2c3              f00dfeed   412.3    amd64  main   false        2026-08-19T18:02:11Z
actions  setup-go-1.25-linux-x64          cafebabe   88.1     amd64         true         2026-08-19T14:40:03Z
bazel    bazel                            3          10240.0  amd64         false        2026-08-19T11:19:45Z
```

| Flag                   | Description                                                                                         |
| :--------------------- | :-------------------------------------------------------------------------------------------------- |
| `--repo`               | Repository (owner/name or bare name). Required.                                                     |
| `--search`             | Filter to cache keys containing this substring.                                                     |
| `--sort-by`            | Sort column: `key`, `version`, `size`, `last_used_at`, `arch`, `scope`. Defaults to `last_used_at`. |
| `--sort-direction`     | `asc` or `desc`. Defaults to `desc`.                                                                |
| `--page`, `--per-page` | Pagination (per-page 1-100, default 50).                                                            |
| `--format`             | `json`, `table`, or `yaml`. Defaults to `json`.                                                     |

## `blacksmith cache delete`

Deletes all Actions cache entries for a repository that exactly match `--key`. By default every version, scope, and transparent-cache variant of the key is deleted; narrow the selection with the optional filters.

```bash theme={"system"}
blacksmith cache delete --repo my-org/my-repo --key node-modules-a1b2c3
```

| Flag                  | Description                                                              |
| :-------------------- | :----------------------------------------------------------------------- |
| `--repo`              | Repository (owner/name or bare name). Required.                          |
| `--key`               | Exact cache key to delete. Required.                                     |
| `--version`           | Restrict deletion to one cache version.                                  |
| `--scope`             | Restrict deletion to one branch scope. Pass `null` for unscoped entries. |
| `--transparent-cache` | Restrict deletion to transparent (`true`) or regular (`false`) entries.  |
| `--yes`               | Skip the confirmation prompt.                                            |

## `blacksmith cache clear`

Deletes all Actions cache entries for a repository.

```bash theme={"system"}
blacksmith cache clear --repo my-org/my-repo --yes
```

| Flag     | Description                                     |
| :------- | :---------------------------------------------- |
| `--repo` | Repository (owner/name or bare name). Required. |
| `--yes`  | Skip the confirmation prompt.                   |

<Note>
  `delete` and `clear` operate on `actions` cache entries. Bazel cache namespaces are listed for visibility, but their storage is managed automatically by Blacksmith's server-side LRU retention and cannot be deleted through the CLI.
</Note>