> 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-run-attach.md). # currents run attach Attach logs, screenshots and other files to a run recorded in CI, after the tests finished, with the currents run attach command `currents run attach` uploads files to a run that CI already recorded, after the test command has finished. For example, the Docker logs of each CI machine, or a screenshot for one test. ## 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`. {% hint style="info" %} The command uses the [Record Key](/guides/record-key.md) the job already uses to report results, passed as `--key` or set as `CURRENTS_RECORD_KEY`. Without a record key, it uses an [API key](/dashboard/administration/api-keys.md) with write access, passed as `--api-key` or set as `CURRENTS_API_KEY`. {% endhint %} Attach the Docker logs of a CI machine to the run: ```bash npx currents run attach --key --project-id --ci-build-id --machine-id shard-1 docker-logs.zip ``` Attach a screenshot to the first attempt of a test: ```bash npx currents run attach --key --project-id --ci-build-id --spec tests/cart.spec.ts --test-title "adds an item" --attempt 0 screenshot.png ``` The command finds the run by the project and the [CI Build ID](/guides/parallelization-guide/ci-build-id.md) the run was recorded with. Set `CURRENTS_CI_BUILD_ID` on the CI job, so the reporting step and this step read the same value. Leave out `--ci-build-id` only if the run was recorded without one, on a CI provider the reporters recognize: the command then finds the run from the CI environment, as the reporter does. The command prints `Attached ()` for each file that arrived, and `Failed : ` on stderr for each file that did not. If any file failed, it exits with `1`. Attach only the failed files again. ## Where the files go | Options | The files are attached to | Types the target takes | | ---------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------- | | No `--spec` | The whole run. With `--machine-id`, the files are listed under that machine. | `attachment` | | `--spec` | The spec file. | `attachment`, `screenshot`, `video` | | `--spec` and `--test-title` | The test. | `attachment` | | `--spec`, `--test-title` and `--attempt` | One attempt of the test. The first attempt is `0`. | `attachment`, `screenshot`, `video`, `trace` | The type of each file comes from its name, as in [currents session](/resources/reporters/currents-cmd/currents-session.md). A file of a type its target does not take is attached as an `attachment`. A `--type` that the target does not take is an error. The spec file must have finished: the command fails for a spec file that is still running. A spec file that runs once per Playwright project matches more than once; pass `--group` to pick one. The whole run takes at most 200 attached files, and so does each spec file with its tests. ## Options | Option | Environment variable | Description | | ------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | `-k, --key ` | `CURRENTS_RECORD_KEY` | The record key. Required unless `--api-key` is set. | | `--api-key ` | `CURRENTS_API_KEY` | An API key with write access. Used when `--key` is not set. | | `-p, --project-id ` | `CURRENTS_PROJECT_ID` | The project ID from the Currents dashboard. Required. | | `--ci-build-id ` | `CURRENTS_CI_BUILD_ID` | The CI build ID the run was recorded with. | | `--machine-id ` | `CURRENTS_MACHINE_ID` | The CI machine the files come from. Files on the whole run are listed by machine when it is set. | | `--spec ` | | Attach to this spec file of the run. | | `--group ` | | The group of the spec file. Requires `--spec`. | | `--test-title ` | | Attach to this test of `--spec`: the full title joined with `" > "`, or its last part. | | `--attempt <n>` | | Attach to this attempt of the test. The first attempt is `0`. | | `--type <type>` | | The type of every file: `trace`, `screenshot`, `video` or `attachment`. Default: taken from the file name. | | `--caption <text>` | | A short description shown with each file. | | `--meta <key=value>` | | A label for each file. Repeat for more, up to 20. A key holds letters, digits, `_` and `-`. | | `--debug` | `CURRENTS_DEBUG` | Print debug logs. Keys are hidden in them. Default: `false`. | A path is a file or a folder. Of a folder, the files directly in it are attached. Hidden files, links, subfolders and empty files are skipped with a warning. A file named `.env` or `.env.*` is refused, and so is a file larger than 1 GiB. ## Example: Docker logs of each CI machine Zip the logs of the machine after the tests, then attach the zip with the machine's ID. ```yaml jobs: run-tests: runs-on: ubuntu-latest strategy: matrix: shard: [1, 2, 3] env: CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }} CURRENTS_PROJECT_ID: ${{ vars.CURRENTS_PROJECT_ID }} CURRENTS_CI_BUILD_ID: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }} steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: "24.x" - run: npm ci - name: Run tests run: npx playwright test --shard=${{ matrix.shard }}/3 - name: Attach the Docker logs if: ${{ always() }} run: | docker compose logs --no-color > docker.log zip docker-logs.zip docker.log npx --package @currents/cmd@2 currents run attach --machine-id shard-${{ matrix.shard }} --caption "Docker logs" docker-logs.zip ``` --- # 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-run-attach.md?ask=<question>&goal=<user_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.