# currents cache

The `currents cache` command stores and retrieves files on CI machines. The files are securely stored in Currents-managed storage. This command is designed to be used in CI environments to facilitate activities like [Sharded runs](/guides/ci-optimization/re-run-only-failed-tests/re-run-only-failed-tests-sharded.md).

`currents cache` stores metadata about CI execution and test artifacts, each cache item has a unique `id.` The `id` can be set manually, or Currents can generate it automatically based on CI environment variables

{% hint style="info" %}
Automatic CI parameters detection is only supported for GitHub Actions and GitLab CI
{% endhint %}

### Usage

To save items from paths `path-1, path-2` to cache, use the following command:

```bash
npx currents cache set --key <record-key> --id <id> --path <path-1,path-2,...path-n>
```

To download cached items and store the files in `--output-dir` use the following command:

```bash
npx currents cache get --key <record-key> --id <id> --output-dir test-results
```

### Subcommands

`get`

* `--id` - used to identify which cache file to retrieve and extract. If not set, Currents will attempt to locate one based on the CI environment. (supports GitHub Actions, and GitLab CI)
* `--key` - Currents [Record Key](/guides/record-key.md)
* `--preset` - use a predefined preset for creating necessary configuration files for implementing CI workflows. See [#cache-presets](#cache-presets "mention").
* `--preset-output <path-to-file>`- path to a file for saving the preset configuration values (default: `.currents_env`)
* `--output-dir <path-to-dir>` - directory for extracting the cache contents to, defaults to `./`
* `--matrix-index <number>` - the node index when using parallel/matrix jobs in CI. Used to correctly identify the node cache, and properly populate shards when using the last-run preset.
* `--matrix-total <number>` - the node total when using parallel/matrix jobs in CI. Used to populate shards when using the last-run preset.
* `--help` - show help message

`set`

* `--id` - used to identify the cache for retrieval later. If not set, Currents will attempt to locate one based on the CI environment. (supports GitHub Actions, and GitLab CI)
* `--key` - Currents [Record Key](/guides/record-key.md)
* `--preset`
  * Use a predefined set of paths and files for cache uploads; the Currents team maintains presets for common CI workflows (for example, [Sharded runs](/guides/ci-optimization/re-run-only-failed-tests/re-run-only-failed-tests-sharded.md)).
* `--path <path-1,path-2>` - use `--path <path-1,path-2>` to provide a comma-separated list of paths to cache.
* `--pw-output-dir <dir>` - Playwright [output directory](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir) containing`.last-run.json` (default: `./test-results`)
* `--matrix-index <number>` - the node index when using parallel/matrix jobs in CI. Used to correctly identify the node cache, and properly populate shards when using the last-run preset.
* `--matrix-total <number>` - the node total when using parallel/matrix jobs in CI. Used to populate shards when using the last-run preset.
* `--help` - show help message

### Cache Presets

Use a predefined set of paths and files for cache uploads with the `--preset` flag; the Currents team maintains presets for common CI workflows, such as rerunning only failed tests or retrieving the CI build ID of previous runs.

#### Preset: last-run

This preset defines a set of rules to implement [Sharded runs](/guides/ci-optimization/re-run-only-failed-tests/re-run-only-failed-tests-sharded.md) flow on various CI providers.

* `currents cache set --preset last-run` will automatically add to cache files necessary to rerun only failed tests ([.last-run.json](/guides/ci-optimization/re-run-only-failed-tests/re-run-only-failed-tests-sharded.md))
* `currents cache get --preset last-run` will fetch the cache contents of the cache and also create the files necessary for rerunning only previously failed tests

The preset output file will contain CI-specific information that should be passed to the Playwright test command. For shard information to be presented correctly, `--matrix-index` and `--matrix-total` must be supplied.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.currents.dev/resources/reporters/currents-cmd/currents-cache.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.