@currents/cmd
CLI tool for Currents - a cloud platform for debugging, troubleshooting, and analyzing CI tests.
Installation
Requires Node.js 22.13 or later.
npm install @currents/cmd --save-dev
Outside a project that installs @currents/cmd, run npx --package @currents/cmd@2 currents. Without the package, npx currents runs an unrelated npm package named currents.
Upgrading from 1.x: see Upgrade @currents/cmd to 2.0.
Upload test results
- Generate test results with one of the supported reporters
- Upload the results
npx currents run upload --project-id=xxx --key=yyy
For JUnit XML reports, run upload converts them to the Currents format first, then uploads them. Put quotes around the --input-file pattern, so that the CLI expands it and not the shell:
npx currents run upload --project-id=xxx --key=yyy --input-format junit --input-file "reports/*.xml" --framework postman
--framework takes cypress, postman, node, vitest or wdio. For Cypress run results saved by after:run, use --input-format cypress-json --input-file results.json without --framework: it uploads every attempt, screenshot and video. The converted reports are saved to --output-dir, or --report-dir, or a new folder in .currents. A folder you name must be empty or not exist yet.
ℹ️ Get familiar with 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 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_DIRor--report-dirto read the results previously generated by one of supported reporters, otherwise - use the most recently created folder named as
.currents/[timestamp]-[uuidv4()]in the current working directory
currents run upload sends the list of every test of the run, which Currents uses to show the progress of a sharded run. It reads the list from fullTestSuite.json, which @currents/jest writes to the report, or builds it from the results. A shard has only the results of its own tests, so without fullTestSuite.json the command runs the Jest installed in the current folder to list the tests of every shard. Run it from the project folder, with Jest 29.5 or later installed. @currents/cmd does not install Jest. In a Detox project, that Jest run loads the test files in the node test environment, so Detox does not start a device. A test file that uses Detox while it loads gets its tests from the results of the shard that ran it, and the command prints a warning.
For Detox runs reported by @currents/jest, currents run upload also attaches the videos, screenshots and logs that Detox recorded to the matching test attempt, adds the element actions of detox.trace.json as steps, and uploads detox.trace.json. Run it after detox test exits: Detox finishes writing the files only then.
currents run upload applies the actions of the project to the results before it sends them. The tests already ran, so each attempt keeps its result, errors and artifacts:
- a skip action marks the test as skipped
- a quarantine action marks a failed test as skipped
- a tag action adds its tags to the test
The dashboard shows which action changed each test. Actions with regex or date conditions are not applied yet. The command uploads the results without actions when it can't get them.
With --fail-on-failures, or CURRENTS_FAIL_ON_FAILURES=true, the command exits with 1 after it uploads the results when a test failed, and lists the failed tests. A test that an action quarantined or skipped does not count. Let the test command pass and use the upload to fail the CI job, so a quarantined test does not fail it:
npx detox test || true
npx currents run upload --fail-on-failures
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 folder containing the test results created with one of the supported 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 | CURRENTS_DEBUG | false |
-t, --tag | string | Comma-separated tag(s) for recorded runs in Currents | CURRENTS_TAG | - |
--environment | string | The environment to label the run with, e.g. staging | CURRENTS_ENVIRONMENT | - |
--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 |
--fail-on-failures | boolean | Exit with 1 after uploading when a test failed. A test quarantined or skipped by a Currents action does not count | CURRENTS_FAIL_ON_FAILURES | false |
An option on the command line wins over its environment variable. The configuration is also available by running the CLI command with the --help argument.
Attach files to a run
currents run attach uploads files, such as logs or screenshots, to a run that CI already recorded. It uses the record key, or an API key with write access when no record key is set:
npx currents run attach --key <record-key> --project-id <id> --ci-build-id <build-id> --machine-id shard-1 docker-logs.zip
npx currents run attach --key <record-key> --project-id <id> --ci-build-id <build-id> --spec tests/cart.spec.ts --test-title "adds an item" --attempt 0 screenshot.png
Without --spec, the files are attached to the whole run. For the options, run npx currents run attach --help.
Share a run
currents run share prints a public link to a run, or to one spec file or test of it, and a link to the same content as Markdown. It uses an API key with write access:
npx currents run share <run-id>
npx currents run share <run-id> --instance-id <instance-id> --test-id <test-id> --purpose fix
--purpose report, the default, holds every test with its attempts and files, for a person. --purpose fix holds the failure context, for an agent fixing the tests. For the options, run npx currents run share --help.
Cancel a run
currents run cancel cancels a run in progress, for example when its CI job is cancelled. It uses the record key:
npx currents run cancel --key <record-key> --project-id <id> --ci-build-id <build-id>
See Cancel Runs on Workflow Cancellation for GitHub Actions.
Capture a session as evidence
currents session captures an agent or browser session, such as a bug before and after a fix. Each command uses the record key, or an API key with write access when no record key is set. In CI, where CURRENTS_RECORD_KEY is already set, nothing else is needed; elsewhere, set an API key once as CURRENTS_API_KEY:
export CURRENTS_API_KEY=<api-key>
npx currents session start --project-id <id> --title "Checkout fails on empty cart" --status failed
npx currents session attach before.png .playwright-mcp/traces
npx currents session share --expires-in-days 7
session share prints a public link to the session page, and a link to the same content as Markdown. For the options, run npx currents session --help.
Use Currents API
- Retrieve information about Currents resources in JSON format. See the REST API docs.
ℹ️ The command requires the --project-id and --api-key from Currents 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 📖 by running the following command:
npx currents run get --ci-build-id <ci-build-id> --output path/to/save/run.json -
Obtain the last completed run data, filtered by
--branchand/or--tag, by running the following command:npx currents run get --branch <branch> --tag <tag-1,tag-2,...tag-n>
For more examples and usage options, run npx currents run get --help.
To call any other REST API route, use currents api with the route path. It reads the API key from --api-key or CURRENTS_API_KEY:
npx currents api /v1/runs/<run-id>
npx currents api /v1/runs/<run-id>/cancel -X PUT
For the 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 is made from the variables of the CI job. When no CI job is detected the ID is random, and the command warns: pass --id to save and restore the same cache.
To cache files, use the following command:
npx currents cache set --key <record-key> --id <id> --path <path-1,path-2,...path-n>
To download files, use the following command:
npx currents cache get --key <record-key> --id <id>
For more examples and usage options, run npx currents cache --help.
Agent skill
The package includes the currents-cli agent skill, which tells coding agents how to use this CLI.
# Print the skill
npx currents skill
# Add it to the project for Codex and Cursor, in .agents/skills/currents-cli
npx currents skill --install
# Add it for Claude Code
npx currents skill --install --dir .claude/skills
The skill is also in this repository, in skills/currents-cli: npx skills add https://github.com/currents-dev/currents-reporter --skill currents-cli.
Guides
npx currents docs lists the guides that ship with the package, such as the CI setup steps. npx currents docs <topic> prints one as Markdown. The guides are in docs/.
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. Keys are hidden in the debug output.
The full documentation is at https://docs.currents.dev/resources/reporters/currents-cmd.