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

# currents run share

Create a public link to a CI run, one spec file or one test, for a person or an agent, with the currents run share command

`currents run share` creates a public link to a run that Currents recorded, or to one spec file or test of the run, and prints the link. Anyone who has the link can open it without a Currents account until it expires. See [Share links](https://docs.currents.dev/ai/reference/share-links.md) for what a link exposes.

`--purpose` selects the kind of link:

* `report` (default): a [Shared Run](https://docs.currents.dev/ai/agentic-testing/share-a-run.md), for a person. It lists the tests with their attempts, errors and files, up to 2,000 tests, and leaves out passed tests first. For a spec file or a test, the link has the same content for that spec file or test only.
* `fix`: a [Fix link](https://docs.currents.dev/ai/agentic-testing/fix-failing-tests.md#share-a-fix-link), for an agent that fixes the tests. It holds the failure context of the failed tests.

## Usage

Run the commands on this page in a project that installs `@currents/cmd` 2.4.0 or later. Elsewhere, replace `npx currents` with `npx --package @currents/cmd@2 currents`.

{% hint style="info" %}
The command needs an [API key](https://docs.currents.dev/resources/authentication/api-keys.md) with write access, passed as `--api-key` or set as `CURRENTS_API_KEY`. A record key cannot share a run: it can share only [sessions](https://docs.currents.dev/resources/reporters/currents-cmd/currents-session.md). To share runs in CI, add `CURRENTS_API_KEY` to the CI secrets.
{% endhint %}

Share a whole run with a reviewer or a colleague outside Currents:

```bash
npx currents run share <run-id>
```

The command prints two lines: the address of the page, then `Markdown: <url>`, the address of the same content as Markdown, for agents.

Give an agent the failures of a whole run:

```bash
npx currents run share <run-id> --purpose fix
```

Share one spec file, for example the copy that ran in the `firefox` group:

```bash
npx currents run share <run-id> --instance-id <instance-id>
```

Give an agent the failures of one spec file:

```bash
npx currents run share <run-id> --instance-id <instance-id> --purpose fix
```

Show one test with every attempt to a person, for example a flaky test:

```bash
npx currents run share <run-id> --instance-id <instance-id> --test-id <test-id>
```

Give an agent one failing test. The link holds the last attempt that failed:

```bash
npx currents run share <run-id> --instance-id <instance-id> --test-id <test-id> --purpose fix
```

Give an agent one attempt of a test. The first attempt is `0`:

```bash
npx currents run share <run-id> --instance-id <instance-id> --test-id <test-id> --purpose fix --attempt 0
```

## Find the IDs

* In the dashboard, the run ID is in the run's URL, after `/run/`. The URL of a test has both other IDs: `/instance/<instance-id>/test/<test-id>`.
* An agent connected to the [Currents MCP server](https://docs.currents.dev/ai/connect.md) gets the IDs from its tools.
* The Markdown of a Fix link lists the IDs of its run, spec files and tests at the end.
* [currents run get](https://docs.currents.dev/resources/reporters/currents-cmd/currents-run-get.md) prints the run with its `runId`. Each item of its `specs` has the `spec` path, the `instanceId` and the `groupId`.

A spec file that runs in more than one group, such as once for each Playwright project, has one instance ID in each group. Find the instance ID of a spec file in the `firefox` group:

```bash
npx currents run get --project-id <project-id> --ci-build-id <ci-build-id> \
  | jq -r '.specs[] | select(.spec == "tests/login.spec.ts" and .groupId == "firefox") | .instanceId'
```

## Options

| Option                     | Environment variable | Description                                                                                                                                        |
| -------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<run-id>`                 |                      | The run to share. Required.                                                                                                                        |
| `--instance-id <id>`       |                      | Share one spec file of the run. Default: the whole run.                                                                                            |
| `--test-id <id>`           |                      | Share one test of the spec file. Requires `--instance-id`.                                                                                         |
| `--attempt <n>`            |                      | Share one attempt of the test. The first attempt is `0`. Requires `--test-id` and `--purpose fix`. Default: the last attempt that failed.          |
| `--purpose <purpose>`      |                      | `report`: the tests with their attempts and files, for a person. `fix`: the failure context, for an agent that fixes the tests. Default: `report`. |
| `--expires-in-days <days>` |                      | How long the link lasts: `1`, `3` or `7` days. Default: `7` for `report`, `1` for `fix`.                                                           |
| `--api-key <api-key>`      | `CURRENTS_API_KEY`   | An API key with write access. Required.                                                                                                            |
| `--debug`                  | `CURRENTS_DEBUG`     | Print debug logs. Keys are hidden in them. Default: `false`.                                                                                       |

## Notes

* The link shows the run as it was when the link was created. Results that arrive later do not appear on it.
* Each `report` call creates a new link. A `fix` call without `--expires-in-days` returns the Fix link that already exists for the same run, spec file or test while more than an hour of it remains, and otherwise creates a new one.
* With `--test-id`, the command checks that the spec file of `--instance-id` belongs to `<run-id>`, and fails if it does not.
* If an organization admin turned off public share links, the command prints the error from the API and exits with `1`. See [Turn off share links](https://docs.currents.dev/ai/reference/share-links.md#turn-off-share-links).

## Example: post the failures of a CI build on the pull request

Find the run of the CI build, create a Fix link to it, and add the link to the pull request as a comment. Both commands read the API key from `CURRENTS_API_KEY`.

{% hint style="warning" %}
Everyone who can read the pull request can open the link, without a Currents account. In a public repository, that is anyone. The traces in it hold request bodies, headers and cookies. See [Share links](https://docs.currents.dev/ai/reference/share-links.md).
{% endhint %}

```bash
RUN_ID=$(npx currents run get --project-id <project-id> --ci-build-id <ci-build-id> | jq -r .runId)
LINK=$(npx currents run share "$RUN_ID" --purpose fix | head -1)
gh pr comment <pr-number> --body "Failed tests: $LINK"
```


---

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