@currents/cmd 1.11.0 → 2.0.0

package/README.md

@@ -14,9 +14,17 @@ npm install @currents/cmd --save-dev
 - Upload the results
 
 ```sh
-npx currents upload --project-id=xxx --key=yyy
+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:
+
+```sh
+npx currents run upload --project-id=xxx --key=yyy --input-format junit --input-file "reports/*.xml" --framework postman
+```
+
+`--framework` takes `postman`, `node`, `vitest` or `wdio`. 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 📖](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
@@ -25,10 +33,10 @@ Obtain `--project-id` and [--key](https://docs.currents.dev/guides/record-key) f
 
 `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
+- use `process.env.CURRENTS_REPORT_DIR` or `--report-dir` to 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
 
-For [Detox](https://wix.github.io/Detox/) runs reported by `@currents/jest`, `currents 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.
+For [Detox](https://wix.github.io/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.
 
 ### Configuration
 
@@ -39,14 +47,14 @@ Please note that all options apart from `--project-id` and `--key` are optional.
 | `-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/*`          |
+| `--report-dir`         | `string`  | The folder 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`                |
+| `--debug`              | `boolean` | Enable debug logs                                                                                                                                            | `CURRENTS_DEBUG`              | `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.
+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.
 
 ## Use Currents API
 
@@ -61,19 +69,28 @@ The configuration is also available by running the CLI command with the `--help`
 - 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
+  npx currents run get --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>
+  npx currents run get --branch <branch> --tag <tag-1,tag-2,...tag-n>
   ```
 
-For more examples and usage options, run `npx currents api --help`.
+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`:
+
+```sh
+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 can be generated based on CI environment variables (only GitHub, GitLab, and Circle CI are supported).
+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:
 
@@ -89,6 +106,23 @@ 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.
+
+```sh
+# 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`.
+
 ## 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.