@currents/cmd/README.md

Currents CLI tools

# @currents/cmd

CLI tool for [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting, and analyzing CI tests.

## Installation

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

## Upload test results

- Generate test results with one of the [supported](https://docs.currents.dev) reporters
- Upload the results

```sh
npx currents upload --project-id=xxx --key=yyy
```

ℹ️ Get familiar with [CI Build ID 📖](https://docs.currents.dev/guides/ci-build-id) before using `currents` in CI. It is **important** to set the `CI Build ID` explicitly using `--ci-build-id` option, if you are using CI sharding or multiple CI machines to parallelize your tests. If not set explicitly, the `CI Build ID` will be set to a random value.

### Notes

Obtain `--project-id` and [--key](https://docs.currents.dev/guides/record-key) from https://app.currents.dev to identify the project and associate the results with your organization.

`currents` will upload the results, as follows:

- use `process.env.CURRENTS_REPORT_DIR` or `--reportDir` to read the results previously generated by one of supported reporters, otherwise
- use the most recently created directory named as `.currents/[timestamp]-[uuidv4()]` in the current working directory

### Configuration

Please note that all options apart from `--project-id` and `--key` are optional.

| Property               | Type      | Description                                                                                                                                                  | Environment variable          | Default                |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | ---------------------- |
| `-k, --key`            | `string`  | The record key to record the results to Currents. Read more: https://currents.dev/readme/guides/record-key                                                   | `CURRENTS_RECORD_KEY`         | -                      |
| `-p, --project-id`     | `string`  | The id of the project for reporting                                                                                                                          | `CURRENTS_PROJECT_ID`         | -                      |
| `--machine-id`         | `string`  | Unique identifier of the machine running the tests. If not provided, it will be generated automatically. See: https://currents.dev/readme/readme?q=machineId | `CURRENTS_MACHINE_ID`         | `[random-string]`      |
| `--report-dir`         | `string`  | The directory containing the test results created with one of the [supported](https://docs.currents.dev) reporters                                           | `CURRENTS_REPORT_DIR`         | `.currents/*`          |
| `--ci-build-id`        | `string`  | The id of the build to record the test run. Read more: https://currents.dev/readme/guides/ci-build-id                                                        | `CURRENTS_CI_BUILD_ID`        | `auto:[random-string]` |
| `--debug`              | `boolean` | Enable debug logs                                                                                                                                            | `DEBUG="currents,currents:*"` | `false`                |
| `-t, --tag`            | `string`  | Comma-separated tag(s) for recorded runs in Currents                                                                                                         | `CURRENTS_TAG`                | -                      |
| `--disable-title-tags` | `boolean` | Disable extracting tags from test title, e.g. `Test name @smoke` would not be tagged with `smoke`                                                            | `CURRENTS_DISABLE_TITLE_TAGS` | `false`                |
| `--remove-title-tags`  | `boolean` | Remove tags from test names in Currents, e.g. `Test name @smoke` becomes `Test name` in the dashboard                                                        | `CURRENTS_REMOVE_TITLE_TAGS`  | `false`                |

The configuration is also available by running the CLI command with the `--help` argument.

## Use Currents API

- Retrieve information about Currents resources in [JSON](https://docs.currents.dev/resources/api/api-resources) format

ℹ️ Please note that the command is experimental and was primarily built to obtain test run data in CI. Its functionality might be extended in the future.

ℹ️ The command requires the `--project-id` and [`--api-key`](https://docs.currents.dev/resources/api/api-keys#managing-the-api-keys) from [Currents](https://app.currents.dev) to authenticate the request and provide the required data. Alternatively, you can set the `CURRENTS_PROJECT_ID` and `CURRENTS_API_KEY` environment variables.

**Supported operations:**

- Obtain run data using the [CI Build ID 📖](https://docs.currents.dev/guides/ci-build-id) by running the following command:

  ```sh
  npx currents api get-run --ci-build-id <ci-build-id> --output path/to/save/run.json
  ```

- Obtain the last completed run data, filtered by `--branch` and/or `--tag`, by running the following command:
  ```sh
  npx currents api get-run --branch <branch> --tag <tag-1,tag-2,...tag-n>
  ```

For more examples and usage options, run `npx currents api --help`.

## Cache test artifacts

The `currents cache` command allows you to archive files from specified locations and save them under an ID in Currents storage. It also stores a meta file with configuration data. You can provide the ID manually or it can be generated based on CI environment variables (only GitHub, GitLab, and Circle CI are supported).

To cache files, use the following command:

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

To download files, use the following command:

```sh
npx currents cache get --key <record-key> --id <id>
```

For more examples and usage options, run `npx currents cache --help`.

## Troubleshooting

Run the CLI command with the `--debug` argument or prefix it with `DEBUG="currents,currents:*"` to obtain detailed information about the command execution process.