> 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.md).

# @currents/cmd

The currents command line tool: upload test results, attach files to a run, get or cancel a run, capture sessions as evidence, cache files between CI jobs, and call the Currents REST API

`@currents/cmd` installs the `currents` command. It uploads test results from reporters that do not send them on their own (Jest, Node.js test runner, JUnit XML), attaches files to runs, gets and cancels runs, captures agent or browser sessions as evidence, caches files between CI jobs, and calls the Currents REST API.

## Requirements

* Node.js 20 or later
* The project ID (see [Project Settings](/dashboard/projects/project-settings.md))
* A [Record Key](/guides/record-key.md) for the commands that record or cancel runs, or an [API key](/dashboard/administration/api-keys.md) for the other commands. See [Credentials](#credentials).

## Install

```bash
npm install @currents/cmd --save-dev
```

In the project, run the command as `npx currents`. Outside a project that installs `@currents/cmd` 2.x, run it as `npx --package @currents/cmd@2 currents`.

{% hint style="warning" %}
`npx currents` without `@currents/cmd` installed downloads and runs an unrelated npm package named `currents`.
{% endhint %}

To upgrade from 1.x, see [Upgrade to 2.0](/resources/reporters/currents-cmd/upgrade-to-v2.md).

## Commands

Run `currents <command> --help` for the options and examples of a command.

Test runs:

* [`currents run upload`](/resources/reporters/currents-cmd/currents-upload.md): upload the results of a Currents reporter, or [convert JUnit XML reports](/resources/reporters/currents-cmd/currents-convert.md) and upload them
* [`currents run attach`](/resources/reporters/currents-cmd/currents-run-attach.md): upload files, such as logs, to a run recorded in CI
* [`currents run get`](/resources/reporters/currents-cmd/currents-run-get.md): get the data of a run
* [`currents run cancel`](/resources/reporters/currents-cmd/currents-cancel.md): cancel a run in progress, for example when its CI job is cancelled

Evidence:

* [`currents session`](/resources/reporters/currents-cmd/currents-session.md): capture an agent or browser session as evidence, attach screenshots and traces, and share a link

CI utilities:

* [`currents cache`](/resources/reporters/currents-cmd/currents-cache.md): save files to the Currents cache and restore them in another CI job

Other:

* [`currents api`](/resources/reporters/currents-cmd/currents-api.md): make an authenticated request to any route of the Currents REST API
* [`currents skill`](/resources/reporters/currents-cmd/currents-skill.md): print or install the agent skill that tells coding agents how to use the CLI

## Credentials

| Command                                              | Key                                                                   | Option               | Environment variable                      |
| ---------------------------------------------------- | --------------------------------------------------------------------- | -------------------- | ----------------------------------------- |
| `run upload`, `run cancel`, `cache set`, `cache get` | [Record key](/guides/record-key.md)                                   | `--key`              | `CURRENTS_RECORD_KEY`                     |
| `run attach`                                         | Record key, or an API key with write access when no record key is set | `--key`, `--api-key` | `CURRENTS_RECORD_KEY`, `CURRENTS_API_KEY` |
| `session start`, `session attach`, `session share`   | API key with write access                                             | `--api-key`          | `CURRENTS_API_KEY`                        |
| `run get`, `api`                                     | [API key](/dashboard/administration/api-keys.md)                      | `--api-key`          | `CURRENTS_API_KEY`                        |

Set keys as environment variables or CI secrets, not as options, so that they stay out of shell history and CI logs.

## Options and environment variables

An option on the command line wins over its environment variable, and the environment variable wins over the default. For a flag such as `CURRENTS_DEBUG`, the values `false`, `0`, `no` and `off` turn it off, and any other value turns it on.

{% hint style="info" %}
If you use CI sharding or several CI machines, set `CURRENTS_CI_BUILD_ID` once for the CI job. The reporter, `run upload`, `run attach` and `run cancel` then find the same run. See [CI Build ID](/guides/parallelization-guide/ci-build-id.md).
{% endhint %}

## Troubleshooting

Run the command with `--debug` to print the requests and the resolved configuration. Keys are replaced with `*****` in the debug output.

`currents` exits with `0` when the command finished, and with `1` otherwise. `currents` without a command prints the help and exits with `1`.


---

# 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.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.