chore: cmd readme [skip ci]

currents-dev · Jul 10, 2024 · daaa7e4 · daaa7e4
1 parent 7cfd93a
commit daaa7e4
Showing 1 changed file with 14 additions and 18 deletions.
diff --git a/packages/cmd/README.md b/packages/cmd/README.md
@@ -1,6 +1,6 @@
 # @currents/cmd
 
-CLI tools for [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting, and analyzing parallel CI tests.
+CLI tool for [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting, and analyzing CI tests.
 
 ## Installation
 
@@ -10,38 +10,38 @@ npm install @currents/cmd --save-dev
 
 ## Usage
 
-Run the CLI command:
+- Generate test results with one of the reporters (see [documentation](https://docs.currents.dev) for the list of supporter reporters)
+- Upload the results
 
 ```sh
 npx currents upload --project-id=xxx --key=yyy
 ```
 
-The command will:
+ℹ️ Get familiar with [CI Build ID 📖](https://docs.currents.dev/guides/ci-build-id) (`--ci-build-id`) before using the tool in CI.
 
-1. Read the configuration.
+## Notes
 
-   The report directory is determined from `process.env.CURRENTS_REPORT_DIR` or `--reportDir`, or the most recently created directory named using the pattern `.currents-report-[timestamp]-[uuidv4()]` in the current working directory.
+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.
 
-   The report directory contains test results grouped by spec file and the configuration information used to obtain them.
+`currents` will upload the results, as follows:
 
-2. Optionally run a full test suite "discovery" process, which will try to find all tests (required for the Currents platform).
+- use `process.env.CURRENTS_REPORT_DIR` or `--reportDir` to read the results previosly generated by one of supported reporters, otherwise
+- use the most recently created directory named as `.currents-report-[timestamp]-[uuidv4()]` in the current working directory
 
-   The full test suite includes the tests that should be part of the same run but executed across different machines.
+> ℹ️ 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 if you are using sharding or multiple machines for the same test run.
 
-3. Upload the test results to the Currents
-
-   The `--project-id` and [--key](https://docs.currents.dev/guides/record-key) are used to identify the project and associate the results with the organization in the Currents dashboard.
+> ℹ️ The `CI Build ID` will be generated automatically if not set.
 
 ## 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 be used to record the results on the remote dashboard. Read more: https://currents.dev/readme/guides/record-key                            | `CURRENTS_RECORD_KEY`         | -                                       |
-| `-p, --project-id`     | `string`  | The id of the project to record the test run.                                                                                                                | `CURRENTS_PROJECT_ID`         | -                                       |
+| `-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 path from where the CLI command will read the Currents report                                                                                            | `CURRENTS_REPORT_DIR`         | `.currents-report-[timestamp]-[uuidv4]` |
+| `--report-dir`         | `string`  | The directory containng the test results created with one of the [supported](https://docs.currents.dev) reporters                                            | `CURRENTS_REPORT_DIR`         | `.currents-report-[timestamp]-[uuidv4]` |
 | `--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:*"` | `falseu`                                |
 | `-t, --tag`            | `string`  | Comma-separated tag(s) for recorded runs in Currents                                                                                                         | `CURRENTS_TAG`                | -                                       |
@@ -50,10 +50,6 @@ Please note that all options apart from `--project-id` and `--key` are optional.
 
 The configuration is also available by running the CLI command with the `--help` argument.
 
-**Note:**
-
-The `CI Build ID` and `Machine ID` will be generated automatically if not set. It is **important** to set the `CI Build ID` explicitly when the results from different machines are part of the same test run. Read more - [here](https://docs.currents.dev/guides/ci-build-id).
-
 ## 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.