> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/resources/reporters/currents-cmd/currents-cache.md). # currents cache Save files to the Currents cache in one CI job and restore them in another with the currents cache command `currents cache set` saves files to Currents-managed storage, and `currents cache get` restores them, for example in a later CI job or a rerun of the same CI job. Use it to [Sharded runs](/guides/ci-optimization/re-run-only-failed-tests/re-run-only-failed-tests-sharded.md). Both commands authenticate with the [Record Key](/guides/record-key.md), passed as `--key` or set as `CURRENTS_RECORD_KEY`. ## Usage Run the commands on this page in a project that installs `@currents/cmd`. Elsewhere, replace `npx currents` with `npx --package @currents/cmd@2 currents`. Save the files of `path-1` and `path-2` under an ID: ```bash npx currents cache set --key --id --path ``` Restore the files saved under the ID to `test-results`: ```bash npx currents cache get --key --id --output-dir test-results ``` ## The cache ID Each cache entry has an ID. Pass the same `--id` to `cache set` and `cache get`, or leave it out and let the commands make it from the CI job: * GitHub Actions: the repository, the run ID and `--matrix-index` * GitLab CI: the pipeline ID and the job name * Other CI providers: the variables that identify the pipeline and the job, and `--matrix-index` When the command detects no CI job, the ID is random, and the command warns `No CI job detected`. Pass `--id` in that case, or `cache get` cannot find what `cache set` saved. ## cache set options | Option | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-k, --key ` | The record key. Environment variable: `CURRENTS_RECORD_KEY`. Required. | | `--id ` | The ID to save the files under. Default: made from the CI job, see [The cache ID](#the-cache-id). | | `--preset ` | `last-run` saves the Playwright `.last-run.json` files of `--pw-output-dir`. See [Presets](#presets). | | `--path ` | Comma-separated paths or glob patterns of the files to save, inside the current folder. Quote globs, for example `"dist/**/*"`. At most 50 MB zipped. | | `--pw-output-dir ` | The Playwright [output folder](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir) that holds `.last-run.json`. Default: `test-results`. | | `--matrix-index ` | The index of this job among parallel jobs, from 1. Each job has its own cache. Pass it when the CI does not tell the jobs apart, as in a GitHub Actions matrix. Default: `1`. | | `--matrix-total ` | GitHub Actions only. The number of jobs in the matrix, for the shards that the `last-run` preset writes. Default: `1`. | | `--continue` | Exit with `0` when no files are found, and save the cache without files. Default: `false`. | | `--debug` | Print debug logs. Keys are hidden in them. Environment variable: `CURRENTS_DEBUG`. Default: `false`. | ## cache get options | Option | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `-k, --key ` | The record key. Environment variable: `CURRENTS_RECORD_KEY`. Required. | | `--id ` | The ID the files were saved under. Default: made from the CI job, see [The cache ID](#the-cache-id). | | `--preset ` | `last-run` restores the saved `.last-run.json` files and writes the Playwright options for the rerun to `--preset-output`. See [Presets](#presets). | | `--output-dir ` | The folder to restore the files to. Default: the current folder. | | `--preset-output ` | The file the `last-run` preset writes, relative to the current folder. Default: `.currents_env`. | | `--matrix-index ` | The index of this job among parallel jobs, from 1. Default: `1`. | | `--matrix-total ` | GitHub Actions only. The number of jobs in the matrix, for the shards that the `last-run` preset writes. Default: `1`. | | `--continue` | Exit with `0` when the cache is not found. Default: `false`. | | `--debug` | Print debug logs. Keys are hidden in them. Environment variable: `CURRENTS_DEBUG`. Default: `false`. | ## Presets `--preset` selects a predefined set of files for a CI workflow. ### Preset: last-run The `last-run` preset implements [Sharded runs](/guides/ci-optimization/re-run-only-failed-tests/re-run-only-failed-tests-sharded.md) on CI providers. * `currents cache set --preset last-run` saves the [.last-run.json](/guides/ci-optimization/re-run-only-failed-tests/re-run-only-failed-tests-sharded.md) files that Playwright writes to `--pw-output-dir`. * `currents cache get --preset last-run` restores them and writes the options for rerunning only the failed tests to `--preset-output`. What `--preset-output` holds depends on the CI provider: * GitHub Actions and CircleCI: options for `playwright test`. * GitLab CI: the shell variables `EXTRA_PW_FLAGS`, `EXTRA_PWCP_FLAGS` and `RUN_ATTEMPT`, to `source` in the job. * Other CI providers: the command writes nothing. For the shards to be correct on GitHub Actions, pass `--matrix-index` and `--matrix-total`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.currents.dev/resources/reporters/currents-cmd/currents-cache.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.